@metamask-previews/utils 11.12.1-preview-9962b7e

package/README.md

@@ -0,0 +1,106 @@
+<table><tr><td><p align="center"><b>⚠️ PLEASE READ ⚠️</b></p><p align="center">This package is currently being migrated to our <a href="https://github.com/MetaMask/core"><code>core</code></a> monorepo. Please do not make any commits to this repository while this migration is taking place, as they will not be transferred over. Also, please re-open PRs that are under active development in the core repo.</p></td></tr></table>
+
+# MetaMask Utils
+
+Various JavaScript/TypeScript utilities of wide relevance to the MetaMask codebase.
+
+## Installation
+
+`yarn add @metamask/utils`
+
+or
+
+`npm install @metamask/utils`
+
+## API
+
+The full API documentation for the latest published version of this library is [available here](https://metamask.github.io/utils/index.html).
+
+## Contributing
+
+### Setup
+
+- Install [Node.js](https://nodejs.org) version 16
+  - If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm use` will automatically choose the right node version for you.
+- Install [Yarn v3](https://yarnpkg.com/getting-started/install)
+- Run `yarn install` to install dependencies and run any required post-install scripts
+
+### Testing and Linting
+
+Run `yarn test` to run the tests once. To run tests on file changes, run `yarn test:watch`.
+
+Run `yarn lint` to run the linter, or run `yarn lint:fix` to run the linter and fix any automatically fixable issues.
+
+### Documentation
+
+The API documentation can be generated with the command `yarn docs`, which saves it in the `./docs` directory. Open the `./docs/index.html` file to browse the documentation.
+
+### Release & Publishing
+
+The project follows the same release process as the other libraries in the MetaMask organization. The GitHub Actions [`action-create-release-pr`](https://github.com/MetaMask/action-create-release-pr) and [`action-publish-release`](https://github.com/MetaMask/action-publish-release) are used to automate the release process; see those repositories for more information about how they work.
+
+1. Choose a release version.
+   - The release version should be chosen according to SemVer. Analyze the changes to see whether they include any breaking changes, new features, or deprecations, then choose the appropriate SemVer version. See [the SemVer specification](https://semver.org/) for more information.
+
+2. If this release is backporting changes onto a previous release, then ensure there is a major version branch for that version (e.g. `1.x` for a `v1` backport release).
+   - The major version branch should be set to the most recent release with that major version. For example, when backporting a `v1.0.2` release, you'd want to ensure there was a `1.x` branch that was set to the `v1.0.1` tag.
+
+3. Trigger the [`workflow_dispatch`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) event [manually](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow) for the `Create Release Pull Request` action to create the release PR.
+   - For a backport release, the base branch should be the major version branch that you ensured existed in step 2. For a normal release, the base branch should be the main branch for that repository (which should be the default value).
+   - This should trigger the [`action-create-release-pr`](https://github.com/MetaMask/action-create-release-pr) workflow to create the release PR.
+
+4. Update the changelog to move each change entry into the appropriate change category ([See here](https://keepachangelog.com/en/1.0.0/#types) for the full list of change categories, and the correct ordering), and edit them to be more easily understood by users of the package.
+   - Generally any changes that don't affect consumers of the package (e.g. lockfile changes or development environment changes) are omitted. Exceptions may be made for changes that might be of interest despite not having an effect upon the published package (e.g. major test improvements, security improvements, improved documentation, etc.).
+   - Try to explain each change in terms that users of the package would understand (e.g. avoid referencing internal variables/concepts).
+   - Consolidate related changes into one change entry if it makes it easier to explain.
+   - Run `yarn auto-changelog validate --rc` to check that the changelog is correctly formatted.
+
+5. Review and QA the release.
+   - If changes are made to the base branch, the release branch will need to be updated with these changes and review/QA will need to restart again. As such, it's probably best to avoid merging other PRs into the base branch while review is underway.
+
+6. Squash & Merge the release.
+   - This should trigger the [`action-publish-release`](https://github.com/MetaMask/action-publish-release) workflow to tag the final release commit and publish the release on GitHub.
+
+7. Publish the release on npm.
+   - Be very careful to use a clean local environment to publish the release, and follow exactly the same steps used during CI.
+   - Use `npm publish --dry-run` to examine the release contents to ensure the correct files are included. Compare to previous releases if necessary (e.g. using `https://unpkg.com/browse/[package name]@[package version]/`).
+   - Once you are confident the release contents are correct, publish the release using `npm publish`.
+
+### Testing changes in other projects using preview builds
+
+If you are working on a pull request and want to test changes in another project before you publish them, you can create a _preview build_ and then configure your project to use it.
+
+#### Creating a preview build
+
+1. Within your pull request, post a comment with the text `@metamaskbot publish-preview`. This starts the `publish-preview` GitHub action, which will create a preview build and publish it to NPM.
+2. After a few minutes, the action should complete and you will see a new comment. Note two things:
+   - The name is scoped to `@metamask-previews` instead of `@metamask`.
+   - The ID of the last commit in the branch is appended to the version, e.g. `1.2.3-preview-e2df9b4` instead of `1.2.3`.
+
+#### Using a preview build
+
+To use a preview build within a project, you need to override the resolution logic for your package manager so that the "production" version of that package is replaced with the preview version. Here's how you do that:
+
+1. Open `package.json` in the project and locate the entry for this package in `dependencies`.
+2. Locate the section responsible for resolution overrides (or create it if it doesn't exist). If you're using Yarn, this is `resolutions`; if you're using NPM or any other package manager, this is `overrides`.
+3. Add a line to this section that mirrors the dependency entry on the left-hand side and points to the preview version on the right-hand side. Note the exact format of the left-hand side will differ based on which version of Yarn or NPM you are using. For example:
+   - For Yarn Modern, you will add something like this to `resolutions`:
+     ```
+     "@metamask/utils@^1.2.3": "npm:@metamask-previews/utils@1.2.3-preview-abcdefg"
+     ```
+   - For Yarn Classic, you will add something like this to `resolutions`:
+     ```
+     "@metamask/utils": "npm:@metamask-previews/utils@1.2.3-preview-abcdefg"
+     ```
+   - For NPM, you will add something like this to `overrides`:
+     ```
+     "@metamask/utils": "npm:@metamask-previews/utils@1.2.3-preview-abcdefg"
+     ```
+4. Run `yarn install`.
+
+#### Updating a preview build
+
+If you make more changes to your pull request and want to create a new preview build:
+
+1. Post another `@metamaskbot` comment on the pull request and wait for the response.
+2. Update the version of the preview build in your project's `package.json`. Make sure to re-run `yarn install`!

package/dist/assert.d.ts

@@ -0,0 +1,61 @@
+import type { Struct } from '@metamask/superstruct';
+export type AssertionErrorConstructor = (new (args: {
+    message: string;
+}) => Error) | ((args: {
+    message: string;
+}) => Error);
+/**
+ * The default error class that is thrown if an assertion fails.
+ */
+export declare class AssertionError extends Error {
+    readonly code = "ERR_ASSERTION";
+    constructor(options: {
+        message: string;
+    });
+}
+/**
+ * Same as Node.js assert.
+ * If the value is falsy, throws an error, does nothing otherwise.
+ *
+ * @throws {@link AssertionError} If value is falsy.
+ * @param value - The test that should be truthy to pass.
+ * @param message - Message to be passed to {@link AssertionError} or an
+ * {@link Error} instance to throw.
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}. If a custom error class is provided for
+ * the `message` argument, this argument is ignored.
+ */
+export declare function assert(value: any, message?: string | Error, ErrorWrapper?: AssertionErrorConstructor): asserts value;
+/**
+ * Assert a value against a Superstruct struct.
+ *
+ * @param value - The value to validate.
+ * @param struct - The struct to validate against.
+ * @param errorPrefix - A prefix to add to the error message. Defaults to
+ * "Assertion failed".
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}.
+ * @throws If the value is not valid.
+ */
+export declare function assertStruct<Type, Schema>(value: unknown, struct: Struct<Type, Schema>, errorPrefix?: string, ErrorWrapper?: AssertionErrorConstructor): asserts value is Type;
+/**
+ * Use in the default case of a switch that you want to be fully exhaustive.
+ * Using this function forces the compiler to enforce exhaustivity during
+ * compile-time.
+ *
+ * @example
+ * ```
+ * const number = 1;
+ * switch (number) {
+ *   case 0:
+ *     ...
+ *   case 1:
+ *     ...
+ *   default:
+ *     assertExhaustive(snapPrefix);
+ * }
+ * ```
+ * @param _object - The object on which the switch is being operated.
+ */
+export declare function assertExhaustive(_object: never): never;
+//# sourceMappingURL=assert.d.ts.map

package/dist/assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAKpD,MAAM,MAAM,yBAAyB,GACjC,CAAC,KAAK,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,KAAK,CAAC,GAC1C,CAAC,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,KAAK,CAAC,CAAC;AAkD3C;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,mBAAmB;IAEhC,YAAY,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,EAEvC;CACF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,GAAG,EACV,OAAO,GAAE,MAAM,GAAG,KAA2B,EAE7C,YAAY,GAAE,yBAA0C,GACvD,OAAO,CAAC,KAAK,CAQf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EACvC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAC5B,WAAW,SAAqB,EAEhC,YAAY,GAAE,yBAA0C,GACvD,OAAO,CAAC,KAAK,IAAI,IAAI,CASvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,KAAK,GAAG,KAAK,CAItD"}

package/dist/assert.js

@@ -0,0 +1,115 @@
+import { assert as assertSuperstruct } from '@metamask/superstruct';
+import { getErrorMessage } from './errors.js';
+/**
+ * Check if a value is a constructor, i.e., a function that can be called with
+ * the `new` keyword.
+ *
+ * @param fn - The value to check.
+ * @returns `true` if the value is a constructor, or `false` otherwise.
+ */
+function isConstructable(fn) {
+    /* istanbul ignore next */
+    return Boolean(typeof fn?.prototype?.constructor?.name === 'string');
+}
+/**
+ * Attempts to obtain the message from a possible error object. If it is
+ * possible to do so, any trailing period will be removed from the message;
+ * otherwise an empty string is returned.
+ *
+ * @param error - The error object to get the message from.
+ * @returns The message without any trailing period if `error` is an object
+ * with a `message` property; the string version of `error` without any trailing
+ * period if it is not `undefined` or `null`; otherwise an empty string.
+ */
+function getErrorMessageWithoutTrailingPeriod(error) {
+    // We'll add our own period.
+    return getErrorMessage(error).replace(/\.$/u, '');
+}
+/**
+ * Initialise an {@link AssertionErrorConstructor} error.
+ *
+ * @param ErrorWrapper - The error class to use.
+ * @param message - The error message.
+ * @returns The error object.
+ */
+function getError(ErrorWrapper, message) {
+    if (isConstructable(ErrorWrapper)) {
+        return new ErrorWrapper({
+            message,
+        });
+    }
+    return ErrorWrapper({
+        message,
+    });
+}
+/**
+ * The default error class that is thrown if an assertion fails.
+ */
+export class AssertionError extends Error {
+    constructor(options) {
+        super(options.message);
+        this.code = 'ERR_ASSERTION';
+    }
+}
+/**
+ * Same as Node.js assert.
+ * If the value is falsy, throws an error, does nothing otherwise.
+ *
+ * @throws {@link AssertionError} If value is falsy.
+ * @param value - The test that should be truthy to pass.
+ * @param message - Message to be passed to {@link AssertionError} or an
+ * {@link Error} instance to throw.
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}. If a custom error class is provided for
+ * the `message` argument, this argument is ignored.
+ */
+export function assert(value, message = 'Assertion failed.', ErrorWrapper = AssertionError) {
+    if (!value) {
+        if (message instanceof Error) {
+            throw message;
+        }
+        throw getError(ErrorWrapper, message);
+    }
+}
+/**
+ * Assert a value against a Superstruct struct.
+ *
+ * @param value - The value to validate.
+ * @param struct - The struct to validate against.
+ * @param errorPrefix - A prefix to add to the error message. Defaults to
+ * "Assertion failed".
+ * @param ErrorWrapper - The error class to throw if the assertion fails.
+ * Defaults to {@link AssertionError}.
+ * @throws If the value is not valid.
+ */
+export function assertStruct(value, struct, errorPrefix = 'Assertion failed', ErrorWrapper = AssertionError) {
+    try {
+        assertSuperstruct(value, struct);
+    }
+    catch (error) {
+        throw getError(ErrorWrapper, `${errorPrefix}: ${getErrorMessageWithoutTrailingPeriod(error)}.`);
+    }
+}
+/**
+ * Use in the default case of a switch that you want to be fully exhaustive.
+ * Using this function forces the compiler to enforce exhaustivity during
+ * compile-time.
+ *
+ * @example
+ * ```
+ * const number = 1;
+ * switch (number) {
+ *   case 0:
+ *     ...
+ *   case 1:
+ *     ...
+ *   default:
+ *     assertExhaustive(snapPrefix);
+ * }
+ * ```
+ * @param _object - The object on which the switch is being operated.
+ */
+export function assertExhaustive(_object) {
+    throw new Error('Invalid branch reached. Should be detected during compilation.');
+}
+//# sourceMappingURL=assert.js.map

package/dist/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,IAAI,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAEpE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAM9C;;;;;;GAMG;AACH,SAAS,eAAe,CACtB,EAA6B;IAE7B,0BAA0B;IAC1B,OAAO,OAAO,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,oCAAoC,CAAC,KAAc;IAC1D,4BAA4B;IAC5B,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AAEH,SAAS,QAAQ,CAAC,YAAuC,EAAE,OAAe;IACxE,IAAI,eAAe,CAAC,YAAY,CAAC,EAAE,CAAC;QAClC,OAAO,IAAI,YAAY,CAAC;YACtB,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IACD,OAAO,YAAY,CAAC;QAClB,OAAO;KACR,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAGvC,YAAY,OAA4B;QACtC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAHhB,SAAI,GAAG,eAAe,CAAC;IAIhC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CACpB,KAAU,EACV,OAAO,GAAmB,mBAAmB,EAE7C,YAAY,GAA8B,cAAc;IAExD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,OAAO,YAAY,KAAK,EAAE,CAAC;YAC7B,MAAM,OAAO,CAAC;QAChB,CAAC;QAED,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAc,EACd,MAA4B,EAC5B,WAAW,GAAG,kBAAkB,EAEhC,YAAY,GAA8B,cAAc;IAExD,IAAI,CAAC;QACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,QAAQ,CACZ,YAAY,EACZ,GAAG,WAAW,KAAK,oCAAoC,CAAC,KAAK,CAAC,GAAG,CAClE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAc;IAC7C,MAAM,IAAI,KAAK,CACb,gEAAgE,CACjE,CAAC;AACJ,CAAC","sourcesContent":["import type { Struct } from '@metamask/superstruct';\nimport { assert as assertSuperstruct } from '@metamask/superstruct';\n\nimport { getErrorMessage } from './errors.js';\n\nexport type AssertionErrorConstructor =\n  | (new (args: { message: string }) => Error)\n  | ((args: { message: string }) => Error);\n\n/**\n * Check if a value is a constructor, i.e., a function that can be called with\n * the `new` keyword.\n *\n * @param fn - The value to check.\n * @returns `true` if the value is a constructor, or `false` otherwise.\n */\nfunction isConstructable(\n  fn: AssertionErrorConstructor,\n): fn is new (args: { message: string }) => Error {\n  /* istanbul ignore next */\n  return Boolean(typeof fn?.prototype?.constructor?.name === 'string');\n}\n\n/**\n * Attempts to obtain the message from a possible error object. If it is\n * possible to do so, any trailing period will be removed from the message;\n * otherwise an empty string is returned.\n *\n * @param error - The error object to get the message from.\n * @returns The message without any trailing period if `error` is an object\n * with a `message` property; the string version of `error` without any trailing\n * period if it is not `undefined` or `null`; otherwise an empty string.\n */\nfunction getErrorMessageWithoutTrailingPeriod(error: unknown): string {\n  // We'll add our own period.\n  return getErrorMessage(error).replace(/\\.$/u, '');\n}\n\n/**\n * Initialise an {@link AssertionErrorConstructor} error.\n *\n * @param ErrorWrapper - The error class to use.\n * @param message - The error message.\n * @returns The error object.\n */\n\nfunction getError(ErrorWrapper: AssertionErrorConstructor, message: string) {\n  if (isConstructable(ErrorWrapper)) {\n    return new ErrorWrapper({\n      message,\n    });\n  }\n  return ErrorWrapper({\n    message,\n  });\n}\n\n/**\n * The default error class that is thrown if an assertion fails.\n */\nexport class AssertionError extends Error {\n  readonly code = 'ERR_ASSERTION';\n\n  constructor(options: { message: string }) {\n    super(options.message);\n  }\n}\n\n/**\n * Same as Node.js assert.\n * If the value is falsy, throws an error, does nothing otherwise.\n *\n * @throws {@link AssertionError} If value is falsy.\n * @param value - The test that should be truthy to pass.\n * @param message - Message to be passed to {@link AssertionError} or an\n * {@link Error} instance to throw.\n * @param ErrorWrapper - The error class to throw if the assertion fails.\n * Defaults to {@link AssertionError}. If a custom error class is provided for\n * the `message` argument, this argument is ignored.\n */\nexport function assert(\n  value: any,\n  message: string | Error = 'Assertion failed.',\n\n  ErrorWrapper: AssertionErrorConstructor = AssertionError,\n): asserts value {\n  if (!value) {\n    if (message instanceof Error) {\n      throw message;\n    }\n\n    throw getError(ErrorWrapper, message);\n  }\n}\n\n/**\n * Assert a value against a Superstruct struct.\n *\n * @param value - The value to validate.\n * @param struct - The struct to validate against.\n * @param errorPrefix - A prefix to add to the error message. Defaults to\n * \"Assertion failed\".\n * @param ErrorWrapper - The error class to throw if the assertion fails.\n * Defaults to {@link AssertionError}.\n * @throws If the value is not valid.\n */\nexport function assertStruct<Type, Schema>(\n  value: unknown,\n  struct: Struct<Type, Schema>,\n  errorPrefix = 'Assertion failed',\n\n  ErrorWrapper: AssertionErrorConstructor = AssertionError,\n): asserts value is Type {\n  try {\n    assertSuperstruct(value, struct);\n  } catch (error) {\n    throw getError(\n      ErrorWrapper,\n      `${errorPrefix}: ${getErrorMessageWithoutTrailingPeriod(error)}.`,\n    );\n  }\n}\n\n/**\n * Use in the default case of a switch that you want to be fully exhaustive.\n * Using this function forces the compiler to enforce exhaustivity during\n * compile-time.\n *\n * @example\n * ```\n * const number = 1;\n * switch (number) {\n *   case 0:\n *     ...\n *   case 1:\n *     ...\n *   default:\n *     assertExhaustive(snapPrefix);\n * }\n * ```\n * @param _object - The object on which the switch is being operated.\n */\nexport function assertExhaustive(_object: never): never {\n  throw new Error(\n    'Invalid branch reached. Should be detected during compilation.',\n  );\n}\n"]}

package/dist/base64.d.ts

@@ -0,0 +1,25 @@
+import type { Struct } from '@metamask/superstruct';
+export type Base64Options = {
+    /**
+     * Is the `=` padding at the end required or not.
+     *
+     * @default false
+     */
+    paddingRequired?: boolean;
+    /**
+     * Which character set should be used.
+     * The sets are based on {@link https://datatracker.ietf.org/doc/html/rfc4648 RFC 4648}.
+     *
+     * @default 'base64'
+     */
+    characterSet?: 'base64' | 'base64url';
+};
+/**
+ * Ensure that a provided string-based struct is valid base64.
+ *
+ * @param struct - The string based struct.
+ * @param options - Optional options to specialize base64 validation. See {@link Base64Options} documentation.
+ * @returns A superstruct validating base64.
+ */
+export declare const base64: <Type extends string, Schema>(struct: Struct<Type, Schema>, options?: Base64Options) => Struct<Type, Schema>;
+//# sourceMappingURL=base64.d.ts.map

package/dist/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAKpD,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;OAIG;IAEH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CACvC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,IAAI,SAAS,MAAM,EAAE,MAAM,UACxC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,YACnB,aAAa,yBA2BvB,CAAC"}

package/dist/base64.js

@@ -0,0 +1,30 @@
+import { pattern } from '@metamask/superstruct';
+import { assert } from './assert.js';
+/**
+ * Ensure that a provided string-based struct is valid base64.
+ *
+ * @param struct - The string based struct.
+ * @param options - Optional options to specialize base64 validation. See {@link Base64Options} documentation.
+ * @returns A superstruct validating base64.
+ */
+export const base64 = (struct, options = {}) => {
+    const paddingRequired = options.paddingRequired ?? false;
+    const characterSet = options.characterSet ?? 'base64';
+    let letters;
+    if (characterSet === 'base64') {
+        letters = String.raw `[A-Za-z0-9+\/]`;
+    }
+    else {
+        assert(characterSet === 'base64url');
+        letters = String.raw `[-_A-Za-z0-9]`;
+    }
+    let re;
+    if (paddingRequired) {
+        re = new RegExp(`^(?:${letters}{4})*(?:${letters}{3}=|${letters}{2}==)?$`, 'u');
+    }
+    else {
+        re = new RegExp(`^(?:${letters}{4})*(?:${letters}{2,3}|${letters}{3}=|${letters}{2}==)?$`, 'u');
+    }
+    return pattern(struct, re);
+};
+//# sourceMappingURL=base64.js.map

package/dist/base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.js","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAmBrC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,MAA4B,EAC5B,OAAO,GAAkB,EAAE,EAC3B,EAAE;IACF,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,KAAK,CAAC;IACzD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,QAAQ,CAAC;IAEtD,IAAI,OAAe,CAAC;IACpB,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,GAAG,MAAM,CAAC,GAAG,CAAA,gBAAgB,CAAC;IACvC,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,YAAY,KAAK,WAAW,CAAC,CAAC;QACrC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAA,eAAe,CAAC;IACtC,CAAC;IAED,IAAI,EAAU,CAAC;IACf,IAAI,eAAe,EAAE,CAAC;QACpB,EAAE,GAAG,IAAI,MAAM,CACb,OAAO,OAAO,WAAW,OAAO,QAAQ,OAAO,UAAU,EACzD,GAAG,CACJ,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,EAAE,GAAG,IAAI,MAAM,CACb,OAAO,OAAO,WAAW,OAAO,SAAS,OAAO,QAAQ,OAAO,UAAU,EACzE,GAAG,CACJ,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC,CAAC","sourcesContent":["import type { Struct } from '@metamask/superstruct';\nimport { pattern } from '@metamask/superstruct';\n\nimport { assert } from './assert.js';\n\nexport type Base64Options = {\n  /**\n   * Is the `=` padding at the end required or not.\n   *\n   * @default false\n   */\n  // Padding is optional in RFC 4648, that's why the default value is false\n  paddingRequired?: boolean;\n  /**\n   * Which character set should be used.\n   * The sets are based on {@link https://datatracker.ietf.org/doc/html/rfc4648 RFC 4648}.\n   *\n   * @default 'base64'\n   */\n  characterSet?: 'base64' | 'base64url';\n};\n\n/**\n * Ensure that a provided string-based struct is valid base64.\n *\n * @param struct - The string based struct.\n * @param options - Optional options to specialize base64 validation. See {@link Base64Options} documentation.\n * @returns A superstruct validating base64.\n */\nexport const base64 = <Type extends string, Schema>(\n  struct: Struct<Type, Schema>,\n  options: Base64Options = {},\n) => {\n  const paddingRequired = options.paddingRequired ?? false;\n  const characterSet = options.characterSet ?? 'base64';\n\n  let letters: string;\n  if (characterSet === 'base64') {\n    letters = String.raw`[A-Za-z0-9+\\/]`;\n  } else {\n    assert(characterSet === 'base64url');\n    letters = String.raw`[-_A-Za-z0-9]`;\n  }\n\n  let re: RegExp;\n  if (paddingRequired) {\n    re = new RegExp(\n      `^(?:${letters}{4})*(?:${letters}{3}=|${letters}{2}==)?$`,\n      'u',\n    );\n  } else {\n    re = new RegExp(\n      `^(?:${letters}{4})*(?:${letters}{2,3}|${letters}{3}=|${letters}{2}==)?$`,\n      'u',\n    );\n  }\n\n  return pattern(struct, re);\n};\n"]}

package/dist/bytes.d.ts

@@ -0,0 +1,198 @@
+import type { Hex } from './hex.js';
+export type Bytes = bigint | number | string | Uint8Array;
+/**
+ * Check if a value is a `Uint8Array`.
+ *
+ * @param value - The value to check.
+ * @returns Whether the value is a `Uint8Array`.
+ */
+export declare function isBytes(value: unknown): value is Uint8Array;
+/**
+ * Assert that a value is a `Uint8Array`.
+ *
+ * @param value - The value to check.
+ * @throws If the value is not a `Uint8Array`.
+ */
+export declare function assertIsBytes(value: unknown): asserts value is Uint8Array;
+/**
+ * Convert a `Uint8Array` to a hexadecimal string.
+ *
+ * @param bytes - The bytes to convert to a hexadecimal string.
+ * @returns The hexadecimal string.
+ */
+export declare function bytesToHex(bytes: Uint8Array): Hex;
+/**
+ * Convert a `Uint8Array` to a `bigint`.
+ *
+ * To convert a `Uint8Array` to a `number` instead, use {@link bytesToNumber}.
+ * To convert a two's complement encoded `Uint8Array` to a `bigint`, use
+ * {@link bytesToSignedBigInt}.
+ *
+ * @param bytes - The bytes to convert to a `bigint`.
+ * @returns The `bigint`.
+ */
+export declare function bytesToBigInt(bytes: Uint8Array): bigint;
+/**
+ * Convert a `Uint8Array` to a signed `bigint`. This assumes that the bytes are
+ * encoded in two's complement.
+ *
+ * To convert a `Uint8Array` to an unsigned `bigint` instead, use
+ * {@link bytesToBigInt}.
+ *
+ * @see https://en.wikipedia.org/wiki/Two%27s_complement
+ * @param bytes - The bytes to convert to a signed `bigint`.
+ * @returns The signed `bigint`.
+ */
+export declare function bytesToSignedBigInt(bytes: Uint8Array): bigint;
+/**
+ * Convert a `Uint8Array` to a `number`.
+ *
+ * To convert a `Uint8Array` to a `bigint` instead, use {@link bytesToBigInt}.
+ *
+ * @param bytes - The bytes to convert to a number.
+ * @returns The number.
+ * @throws If the resulting number is not a safe integer.
+ */
+export declare function bytesToNumber(bytes: Uint8Array): number;
+/**
+ * Convert a UTF-8 encoded `Uint8Array` to a `string`.
+ *
+ * @param bytes - The bytes to convert to a string.
+ * @returns The string.
+ */
+export declare function bytesToString(bytes: Uint8Array): string;
+/**
+ * Convert a `Uint8Array` to a base64 encoded string.
+ *
+ * @param bytes - The bytes to convert to a base64 encoded string.
+ * @returns The base64 encoded string.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Convert a hexadecimal string to a `Uint8Array`. The string can optionally be
+ * prefixed with `0x`. It accepts even and odd length strings.
+ *
+ * If the value is "0x", an empty `Uint8Array` is returned.
+ *
+ * @param value - The hexadecimal string to convert to bytes.
+ * @returns The bytes as `Uint8Array`.
+ */
+export declare function hexToBytes(value: string): Uint8Array;
+/**
+ * Convert a `bigint` to a `Uint8Array`.
+ *
+ * This assumes that the `bigint` is an unsigned integer. To convert a signed
+ * `bigint` instead, use {@link signedBigIntToBytes}.
+ *
+ * @param value - The bigint to convert to bytes.
+ * @returns The bytes as `Uint8Array`.
+ */
+export declare function bigIntToBytes(value: bigint): Uint8Array;
+/**
+ * Convert a signed `bigint` to a `Uint8Array`. This uses two's complement
+ * encoding to represent negative numbers.
+ *
+ * To convert an unsigned `bigint` to a `Uint8Array` instead, use
+ * {@link bigIntToBytes}.
+ *
+ * @see https://en.wikipedia.org/wiki/Two%27s_complement
+ * @param value - The number to convert to bytes.
+ * @param byteLength - The length of the resulting `Uint8Array`. If the number
+ * is larger than the maximum value that can be represented by the given length,
+ * an error is thrown.
+ * @returns The bytes as `Uint8Array`.
+ */
+export declare function signedBigIntToBytes(value: bigint, byteLength: number): Uint8Array;
+/**
+ * Convert a `number` to a `Uint8Array`.
+ *
+ * @param value - The number to convert to bytes.
+ * @returns The bytes as `Uint8Array`.
+ * @throws If the number is not a safe integer.
+ */
+export declare function numberToBytes(value: number): Uint8Array;
+/**
+ * Convert a `string` to a UTF-8 encoded `Uint8Array`.
+ *
+ * @param value - The string to convert to bytes.
+ * @returns The bytes as `Uint8Array`.
+ */
+export declare function stringToBytes(value: string): Uint8Array;
+/**
+ * Convert a base64 encoded string to a `Uint8Array`.
+ *
+ * @param value - The base64 encoded string to convert to bytes.
+ * @returns The bytes as `Uint8Array`.
+ */
+export declare function base64ToBytes(value: string): Uint8Array;
+/**
+ * Convert a byte-like value to a `Uint8Array`. The value can be a `Uint8Array`,
+ * a `bigint`, a `number`, or a `string`.
+ *
+ * This will attempt to guess the type of the value based on its type and
+ * contents. For more control over the conversion, use the more specific
+ * conversion functions, such as {@link hexToBytes} or {@link stringToBytes}.
+ *
+ * If the value is a `string`, and it is prefixed with `0x`, it will be
+ * interpreted as a hexadecimal string. Otherwise, it will be interpreted as a
+ * UTF-8 string. To convert a hexadecimal string to bytes without interpreting
+ * it as a UTF-8 string, use {@link hexToBytes} instead.
+ *
+ * If the value is a `bigint`, it is assumed to be unsigned. To convert a signed
+ * `bigint` to bytes, use {@link signedBigIntToBytes} instead.
+ *
+ * If the value is a `Uint8Array`, it will be returned as-is.
+ *
+ * @param value - The value to convert to bytes.
+ * @returns The bytes as `Uint8Array`.
+ */
+export declare function valueToBytes(value: Bytes): Uint8Array;
+/**
+ * Concatenate multiple byte-like values into a single `Uint8Array`. The values
+ * can be `Uint8Array`, `bigint`, `number`, or `string`. This uses
+ * {@link valueToBytes} under the hood to convert each value to bytes. Refer to
+ * the documentation of that function for more information.
+ *
+ * @param values - The values to concatenate.
+ * @returns The concatenated bytes as `Uint8Array`.
+ */
+export declare function concatBytes(values: Bytes[]): Uint8Array;
+/**
+ * Create a {@link DataView} from a {@link Uint8Array}. This is a convenience
+ * function that avoids having to create a {@link DataView} manually, which
+ * requires passing the `byteOffset` and `byteLength` parameters every time.
+ *
+ * Not passing the `byteOffset` and `byteLength` parameters can result in
+ * unexpected behavior when the {@link Uint8Array} is a view of a larger
+ * {@link ArrayBuffer}, e.g., when using {@link Uint8Array.subarray}.
+ *
+ * This function also supports Node.js {@link Buffer}s.
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array([1, 2, 3]);
+ *
+ * // This is equivalent to:
+ * // const dataView = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+ * const dataView = createDataView(bytes);
+ * ```
+ * @param bytes - The bytes to create the {@link DataView} from.
+ * @returns The {@link DataView}.
+ */
+export declare function createDataView(bytes: Uint8Array): DataView;
+/**
+ * Compare two Uint8Arrays using a constant-time style loop to reduce timing
+ * side-channels when comparing sensitive data (e.g., mnemonic bytes, keys,
+ * authentication tags). Does not early-return on the first difference:
+ * work done depends only on the input lengths, so byte content does not affect timing.
+ *
+ * When to use:
+ * - Use for secret or security-sensitive byte comparisons to avoid content-based timing leaks.
+ * - Prefer when inputs are fixed-length (or validated to equal length) at the API boundary.
+ *
+ * @param a - The first Uint8Array to compare.
+ * @param b - The second Uint8Array to compare.
+ * @returns Whether the Uint8Arrays are equal.
+ */
+export declare function areUint8ArraysEqual(a: Uint8Array, b: Uint8Array): boolean;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAUpC,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAwC1D;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,CAgBjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAKvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAU7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAWvD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIvD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAoCpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAMvD;AAkBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,UAAU,CAqBZ;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAUvD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAIvD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAIvD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,UAAU,CAsBrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,UAAU,CAqBvD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,CAe1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAazE"}