@metamask/snaps-utils 0.24.0 → 0.25.0

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAIA,2CAAqD;AACrD,mCAA8C;AAC9C,6CAUqB;AAGrB,IAAY,gBAGX;AAHD,WAAY,gBAAgB;IAC1B,gDAA4B,CAAA;IAC5B,mDAA+B,CAAA;AACjC,CAAC,EAHW,gBAAgB,GAAhB,wBAAgB,KAAhB,wBAAgB,QAG3B;AAED;;GAEG;AACU,QAAA,aAAa,GAAG,IAAA,oBAAM,EAAC,IAAA,oBAAM,GAAE,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE;IACjE,OAAO,IAAA,cAAW,EAAC,KAAK,CAAC,KAAK,IAAI,CAAC;AACrC,CAAC,CAAC,CAAC;AAEU,QAAA,UAAU,GAAG,IAAA,kBAAI,EAC5B,IAAA,qBAAO,EACL,IAAA,oBAAM,GAAE,EACR,6DAA6D,CAC9D,EACD,CAAC,EACD,GAAG,CACJ,CAAC;AAEF,2EAA2E;AAC3E,sBAAsB;AACT,QAAA,wBAAwB,GAAG,IAAA,kBAAI,EAAC;IAC3C,OAAO,EAAE,qBAAa;IACtB,IAAI,EAAE,kBAAU;IAChB,IAAI,EAAE,IAAA,sBAAQ,EAAC,IAAA,kBAAI,EAAC,IAAA,oBAAM,GAAE,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC3C,UAAU,EAAE,IAAA,sBAAQ,EAClB,IAAA,oBAAM,EAAC;QACL,IAAI,EAAE,IAAA,kBAAI,EAAC,IAAA,oBAAM,GAAE,EAAE,CAAC,EAAE,QAAQ,CAAC;QACjC,GAAG,EAAE,IAAA,kBAAI,EAAC,IAAA,oBAAM,GAAE,EAAE,CAAC,EAAE,QAAQ,CAAC;KACjC,CAAC,CACH;CACF,CAAC,CAAC;AAKH;;;;;GAKG;AACH,SAAgB,oBAAoB,CAClC,KAAc;IAEd,OAAO,IAAA,gBAAE,EAAC,KAAK,EAAE,gCAAwB,CAAC,CAAC;AAC7C,CAAC;AAJD,oDAIC;AAED;;;;;GAKG;AACH,SAAgB,0BAA0B,CACxC,KAAc;IAEd,IAAA,oBAAY,EACV,KAAK,EACL,gCAAwB,EACxB,IAAI,gBAAgB,CAAC,WAAW,cAAc,CAC/C,CAAC;AACJ,CAAC;AARD,gEAQC;AAuBD;;GAEG;AACH,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,8BAAY,CAAA;IACZ,kCAAgB,CAAA;AAClB,CAAC,EAHW,cAAc,GAAd,sBAAc,KAAd,sBAAc,QAGzB;AAID;;;GAGG;AACH,IAAY,2BAKX;AALD,WAAY,2BAA2B;IACrC,uEAAsC,CAAA;IACtC,6EAA4C,CAAA;IAC5C,mFAAkD,CAAA;IAClD,2EAA0C,CAAA;AAC5C,CAAC,EALW,2BAA2B,GAA3B,mCAA2B,KAA3B,mCAA2B,QAKtC;AAED,IAAY,iBAGX;AAHD,WAAY,iBAAiB;IAC3B,yCAAoB,CAAA;IACpB,wCAAmB,CAAA;AACrB,CAAC,EAHW,iBAAiB,GAAjB,yBAAiB,KAAjB,yBAAiB,QAG5B;AAED,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,4CAA6B,CAAA;IAC7B,8CAA+B,CAAA;IAC/B,sCAAuB,CAAA;IACvB,sCAAuB,CAAA;AACzB,CAAC,EALW,WAAW,GAAX,mBAAW,KAAX,mBAAW,QAKtB;AAEY,QAAA,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC","sourcesContent":["import {\n  SnapFunctionExports,\n  SnapKeyring as Keyring,\n} from '@metamask/snaps-types';\nimport { assertStruct, Json } from '@metamask/utils';\nimport { valid as validSemver } from 'semver';\nimport {\n  Infer,\n  is,\n  object,\n  optional,\n  pattern,\n  refine,\n  size,\n  string,\n  type,\n} from 'superstruct';\nimport { SnapManifest } from './manifest/validation';\n\nexport enum NpmSnapFileNames {\n  PackageJson = 'package.json',\n  Manifest = 'snap.manifest.json',\n}\n\n/**\n * A struct for validating a version string.\n */\nexport const VersionStruct = refine(string(), 'Version', (value) => {\n  return validSemver(value) !== null;\n});\n\nexport const NameStruct = size(\n  pattern(\n    string(),\n    /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\\/)?[a-z0-9-~][a-z0-9-._~]*$/u,\n  ),\n  1,\n  214,\n);\n\n// Note we use `type` instead of `object` here, because the latter does not\n// allow unknown keys.\nexport const NpmSnapPackageJsonStruct = type({\n  version: VersionStruct,\n  name: NameStruct,\n  main: optional(size(string(), 1, Infinity)),\n  repository: optional(\n    object({\n      type: size(string(), 1, Infinity),\n      url: size(string(), 1, Infinity),\n    }),\n  ),\n});\n\nexport type NpmSnapPackageJson = Infer<typeof NpmSnapPackageJsonStruct> &\n  Record<string, any>;\n\n/**\n * Check if the given value is a valid {@link NpmSnapPackageJson} object.\n *\n * @param value - The value to check.\n * @returns Whether the value is a valid {@link NpmSnapPackageJson} object.\n */\nexport function isNpmSnapPackageJson(\n  value: unknown,\n): value is NpmSnapPackageJson {\n  return is(value, NpmSnapPackageJsonStruct);\n}\n\n/**\n * Asserts that the given value is a valid {@link NpmSnapPackageJson} object.\n *\n * @param value - The value to check.\n * @throws If the value is not a valid {@link NpmSnapPackageJson} object.\n */\nexport function assertIsNpmSnapPackageJson(\n  value: unknown,\n): asserts value is NpmSnapPackageJson {\n  assertStruct(\n    value,\n    NpmSnapPackageJsonStruct,\n    `\"${NpmSnapFileNames.PackageJson}\" is invalid`,\n  );\n}\n\n/**\n * An object for storing parsed but unvalidated Snap file contents.\n */\nexport type UnvalidatedSnapFiles = {\n  manifest?: Json;\n  packageJson?: Json;\n  sourceCode?: string;\n  svgIcon?: string;\n};\n\n/**\n * An object for storing the contents of Snap files that have passed JSON\n * Schema validation, or are non-empty if they are strings.\n */\nexport type SnapFiles = {\n  manifest: SnapManifest;\n  packageJson: NpmSnapPackageJson;\n  sourceCode: string;\n  svgIcon?: string;\n};\n\n/**\n * The possible prefixes for snap ids.\n */\nexport enum SnapIdPrefixes {\n  npm = 'npm:',\n  local = 'local:',\n}\n\nexport type SnapId = string;\n\n/**\n * Snap validation failure reason codes that are programmatically fixable\n * if validation occurs during development.\n */\nexport enum SnapValidationFailureReason {\n  NameMismatch = '\"name\" field mismatch',\n  VersionMismatch = '\"version\" field mismatch',\n  RepositoryMismatch = '\"repository\" field mismatch',\n  ShasumMismatch = '\"shasum\" field mismatch',\n}\n\nexport enum SNAP_STREAM_NAMES {\n  JSON_RPC = 'jsonRpc',\n  COMMAND = 'command',\n}\n\nexport enum HandlerType {\n  OnRpcRequest = 'onRpcRequest',\n  OnTransaction = 'onTransaction',\n  SnapKeyring = 'keyring',\n  OnCronjob = 'onCronjob',\n}\n\nexport const SNAP_EXPORT_NAMES = Object.values(HandlerType);\n\nexport type SnapRpcHookArgs = {\n  origin: string;\n  handler: HandlerType;\n  request: Record<string, unknown>;\n};\n\n// The snap is the callee\nexport type SnapRpcHook = (options: SnapRpcHookArgs) => Promise<unknown>;\n\ntype ObjectParameters<\n  Type extends Record<string, (...args: any[]) => unknown>,\n> = Parameters<Type[keyof Type]>;\n\ntype KeyringParameter<Fn> = Fn extends (...args: any[]) => unknown\n  ? Parameters<Fn>\n  : never;\n\ntype KeyringParameters = KeyringParameter<Keyring[keyof Keyring]>;\n\nexport type SnapExportsParameters =\n  | ObjectParameters<SnapFunctionExports>\n  | KeyringParameters;\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAIA,2CAAqD;AACrD,6CASqB;AAGrB,yCAA2C;AAE3C,IAAY,gBAGX;AAHD,WAAY,gBAAgB;IAC1B,gDAA4B,CAAA;IAC5B,mDAA+B,CAAA;AACjC,CAAC,EAHW,gBAAgB,GAAhB,wBAAgB,KAAhB,wBAAgB,QAG3B;AAEY,QAAA,UAAU,GAAG,IAAA,kBAAI,EAC5B,IAAA,qBAAO,EACL,IAAA,oBAAM,GAAE,EACR,6DAA6D,CAC9D,EACD,CAAC,EACD,GAAG,CACJ,CAAC;AAEF,2EAA2E;AAC3E,sBAAsB;AACT,QAAA,wBAAwB,GAAG,IAAA,kBAAI,EAAC;IAC3C,OAAO,EAAE,wBAAa;IACtB,IAAI,EAAE,kBAAU;IAChB,IAAI,EAAE,IAAA,sBAAQ,EAAC,IAAA,kBAAI,EAAC,IAAA,oBAAM,GAAE,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC3C,UAAU,EAAE,IAAA,sBAAQ,EAClB,IAAA,oBAAM,EAAC;QACL,IAAI,EAAE,IAAA,kBAAI,EAAC,IAAA,oBAAM,GAAE,EAAE,CAAC,EAAE,QAAQ,CAAC;QACjC,GAAG,EAAE,IAAA,kBAAI,EAAC,IAAA,oBAAM,GAAE,EAAE,CAAC,EAAE,QAAQ,CAAC;KACjC,CAAC,CACH;CACF,CAAC,CAAC;AAKH;;;;;GAKG;AACH,SAAgB,oBAAoB,CAClC,KAAc;IAEd,OAAO,IAAA,gBAAE,EAAC,KAAK,EAAE,gCAAwB,CAAC,CAAC;AAC7C,CAAC;AAJD,oDAIC;AAED;;;;;GAKG;AACH,SAAgB,0BAA0B,CACxC,KAAc;IAEd,IAAA,oBAAY,EACV,KAAK,EACL,gCAAwB,EACxB,IAAI,gBAAgB,CAAC,WAAW,cAAc,CAC/C,CAAC;AACJ,CAAC;AARD,gEAQC;AAuBD;;GAEG;AACH,yDAAyD;AACzD,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,8BAAY,CAAA;IACZ,kCAAgB,CAAA;AAClB,CAAC,EAHW,cAAc,GAAd,sBAAc,KAAd,sBAAc,QAGzB;AAKD;;;GAGG;AACH,IAAY,2BAKX;AALD,WAAY,2BAA2B;IACrC,uEAAsC,CAAA;IACtC,6EAA4C,CAAA;IAC5C,mFAAkD,CAAA;IAClD,2EAA0C,CAAA;AAC5C,CAAC,EALW,2BAA2B,GAA3B,mCAA2B,KAA3B,mCAA2B,QAKtC;AAED,yDAAyD;AACzD,IAAY,iBAGX;AAHD,WAAY,iBAAiB;IAC3B,yCAAoB,CAAA;IACpB,wCAAmB,CAAA;AACrB,CAAC,EAHW,iBAAiB,GAAjB,yBAAiB,KAAjB,yBAAiB,QAG5B;AACD,wDAAwD;AAExD,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,4CAA6B,CAAA;IAC7B,8CAA+B,CAAA;IAC/B,sCAAuB,CAAA;IACvB,sCAAuB,CAAA;AACzB,CAAC,EALW,WAAW,GAAX,mBAAW,KAAX,mBAAW,QAKtB;AAEY,QAAA,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC","sourcesContent":["import {\n  SnapFunctionExports,\n  SnapKeyring as Keyring,\n} from '@metamask/snaps-types';\nimport { assertStruct, Json } from '@metamask/utils';\nimport {\n  Infer,\n  is,\n  object,\n  optional,\n  pattern,\n  size,\n  string,\n  type,\n} from 'superstruct';\n\nimport { SnapManifest } from './manifest/validation';\nimport { VersionStruct } from './versions';\n\nexport enum NpmSnapFileNames {\n  PackageJson = 'package.json',\n  Manifest = 'snap.manifest.json',\n}\n\nexport const NameStruct = size(\n  pattern(\n    string(),\n    /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\\/)?[a-z0-9-~][a-z0-9-._~]*$/u,\n  ),\n  1,\n  214,\n);\n\n// Note we use `type` instead of `object` here, because the latter does not\n// allow unknown keys.\nexport const NpmSnapPackageJsonStruct = type({\n  version: VersionStruct,\n  name: NameStruct,\n  main: optional(size(string(), 1, Infinity)),\n  repository: optional(\n    object({\n      type: size(string(), 1, Infinity),\n      url: size(string(), 1, Infinity),\n    }),\n  ),\n});\n\nexport type NpmSnapPackageJson = Infer<typeof NpmSnapPackageJsonStruct> &\n  Record<string, any>;\n\n/**\n * Check if the given value is a valid {@link NpmSnapPackageJson} object.\n *\n * @param value - The value to check.\n * @returns Whether the value is a valid {@link NpmSnapPackageJson} object.\n */\nexport function isNpmSnapPackageJson(\n  value: unknown,\n): value is NpmSnapPackageJson {\n  return is(value, NpmSnapPackageJsonStruct);\n}\n\n/**\n * Asserts that the given value is a valid {@link NpmSnapPackageJson} object.\n *\n * @param value - The value to check.\n * @throws If the value is not a valid {@link NpmSnapPackageJson} object.\n */\nexport function assertIsNpmSnapPackageJson(\n  value: unknown,\n): asserts value is NpmSnapPackageJson {\n  assertStruct(\n    value,\n    NpmSnapPackageJsonStruct,\n    `\"${NpmSnapFileNames.PackageJson}\" is invalid`,\n  );\n}\n\n/**\n * An object for storing parsed but unvalidated Snap file contents.\n */\nexport type UnvalidatedSnapFiles = {\n  manifest?: Json;\n  packageJson?: Json;\n  sourceCode?: string;\n  svgIcon?: string;\n};\n\n/**\n * An object for storing the contents of Snap files that have passed JSON\n * Schema validation, or are non-empty if they are strings.\n */\nexport type SnapFiles = {\n  manifest: SnapManifest;\n  packageJson: NpmSnapPackageJson;\n  sourceCode: string;\n  svgIcon?: string;\n};\n\n/**\n * The possible prefixes for snap ids.\n */\n/* eslint-disable @typescript-eslint/naming-convention */\nexport enum SnapIdPrefixes {\n  npm = 'npm:',\n  local = 'local:',\n}\n/* eslint-enable @typescript-eslint/naming-convention */\n\nexport type SnapId = string;\n\n/**\n * Snap validation failure reason codes that are programmatically fixable\n * if validation occurs during development.\n */\nexport enum SnapValidationFailureReason {\n  NameMismatch = '\"name\" field mismatch',\n  VersionMismatch = '\"version\" field mismatch',\n  RepositoryMismatch = '\"repository\" field mismatch',\n  ShasumMismatch = '\"shasum\" field mismatch',\n}\n\n/* eslint-disable @typescript-eslint/naming-convention */\nexport enum SNAP_STREAM_NAMES {\n  JSON_RPC = 'jsonRpc',\n  COMMAND = 'command',\n}\n/* eslint-enable @typescript-eslint/naming-convention */\n\nexport enum HandlerType {\n  OnRpcRequest = 'onRpcRequest',\n  OnTransaction = 'onTransaction',\n  SnapKeyring = 'keyring',\n  OnCronjob = 'onCronjob',\n}\n\nexport const SNAP_EXPORT_NAMES = Object.values(HandlerType);\n\nexport type SnapRpcHookArgs = {\n  origin: string;\n  handler: HandlerType;\n  request: Record<string, unknown>;\n};\n\n// The snap is the callee\nexport type SnapRpcHook = (options: SnapRpcHookArgs) => Promise<unknown>;\n\ntype ObjectParameters<\n  Type extends Record<string, (...args: any[]) => unknown>,\n> = Parameters<Type[keyof Type]>;\n\ntype KeyringParameter<Fn> = Fn extends (...args: any[]) => unknown\n  ? Parameters<Fn>\n  : never;\n\ntype KeyringParameters = KeyringParameter<Keyring[keyof Keyring]>;\n\nexport type SnapExportsParameters =\n  | ObjectParameters<SnapFunctionExports>\n  | KeyringParameters;\n\n// We use a symbol property name instead of { _type: Brand }, because that would show up in IDE suggestions,\n// while internal symbols do not.\ndeclare const brand: unique symbol;\nexport type Opaque<Base, Brand extends symbol> = Base & { [brand]: Brand };\n"]}

package/dist/versions.d.ts

@@ -1,5 +1,80 @@
 import { Json } from '@metamask/utils';
-export declare const DEFAULT_REQUESTED_SNAP_VERSION = "*";
+import { Struct } from 'superstruct';
+import { Opaque } from './types';
+export declare const DEFAULT_REQUESTED_SNAP_VERSION: SemVerRange;
+/**
+ * {@link https://codemix.com/opaque-types-in-javascript/ Opaque} type for SemVer ranges.
+ *
+ * @example Use {@link assertIsSemVerRange} and {@link isValidSemVerRange} to cast to proper type.
+ * ```typescript
+ * const unsafeRange: string = dataFromUser();
+ * assertIsSemVerRange(unsafeRange);
+ * unsafeRange
+ * // ^? SemVerRange
+ * ```
+ * @example If you know what you're doing and want to side-step type safety, casting from a string works correctly.
+ * ```typescript
+ * const unsafeRange: string = dataFromUser();
+ * unsafeRange as SemVerRange;
+ * // ^? SemVerRange
+ * ```
+ * @see {@link assertIsSemVerRange}
+ * @see {@link isValidSemVerRange}
+ */
+export declare type SemVerRange = Opaque<string, typeof semVerRange>;
+declare const semVerRange: unique symbol;
+/**
+ * {@link https://codemix.com/opaque-types-in-javascript/ Opaque} type for singular SemVer version.
+ *
+ * @example Use {@link assertIsSemVerVersion} and {@link isValidSemVerVersion} to cast to proper type.
+ * ```typescript
+ * const unsafeVersion: string = dataFromUser();
+ * assertIsSemVerVersion(unsafeRange);
+ * unsafeVersion
+ * // ^? SemVerVersion
+ * ```
+ * @example If you know what you're doing and want to side-step type safety, casting from a string works correctly.
+ * ```typescript
+ * const unsafeVersion: string = dataFromUser();
+ * unsafeRange as SemVerVersion;
+ * // ^? SemVerVersion
+ * ```
+ * @see {@link assertIsSemVerVersion}
+ * @see {@link isValidSemVerVersion}
+ */
+export declare type SemVerVersion = Opaque<string, typeof semVerVersion>;
+declare const semVerVersion: unique symbol;
+/**
+ * A struct for validating a version string.
+ */
+export declare const VersionStruct: Struct<SemVerVersion, null>;
+export declare const VersionRangeStruct: Struct<SemVerRange, null>;
+/**
+ * Checks whether a SemVer version is valid.
+ *
+ * @param version - A potential version.
+ * @returns `true` if the version is valid, and `false` otherwise.
+ */
+export declare function isValidSemVerVersion(version: unknown): version is SemVerVersion;
+/**
+ * Checks whether a SemVer version range is valid.
+ *
+ * @param versionRange - A potential version range.
+ * @returns `true` if the version range is valid, and `false` otherwise.
+ */
+export declare function isValidSemVerRange(versionRange: unknown): versionRange is SemVerRange;
+/**
+ * Asserts that a value is a valid concrete SemVer version.
+ *
+ * @param version - A potential SemVer concrete version.
+ */
+export declare function assertIsSemVerVersion(version: unknown): asserts version is SemVerVersion;
+/**
+ * Asserts that a value is a valid SemVer range.
+ *
+ * @param range - A potential SemVer range.
+ */
+export declare function assertIsSemVerRange(range: unknown): asserts range is SemVerRange;
 /**
  * Checks whether a SemVer version is greater than another.
  *
@@ -7,7 +82,7 @@ export declare const DEFAULT_REQUESTED_SNAP_VERSION = "*";
  * @param version2 - The right-hand version.
  * @returns `version1 > version2`.
  */
-export declare function gtVersion(version1: string, version2: string): boolean;
+export declare function gtVersion(version1: SemVerVersion, version2: SemVerVersion): boolean;
 /**
  * Returns whether a SemVer version satisfies a SemVer range.
  *
@@ -15,7 +90,7 @@ export declare function gtVersion(version1: string, version2: string): boolean;
  * @param versionRange - The SemVer version range to check against.
  * @returns Whether the version satisfied the version range.
  */
-export declare function satisfiesVersionRange(version: string, versionRange: string): boolean;
+export declare function satisfiesVersionRange(version: SemVerVersion, versionRange: SemVerRange): boolean;
 /**
  * Return the highest version in the list that satisfies the range, or `null` if
  * none of them do. For the satisfaction check, pre-release versions will only
@@ -26,7 +101,7 @@ export declare function satisfiesVersionRange(version: string, versionRange: str
  * @returns The highest version in the list that satisfies the range,
  * or `null` if none of them do.
  */
-export declare function getTargetVersion(versions: string[], versionRange: string): string | null;
+export declare function getTargetVersion(versions: SemVerVersion[], versionRange: SemVerRange): SemVerVersion | null;
 /**
  * Parse a version received by some subject attempting to access a snap.
  *
@@ -34,11 +109,5 @@ export declare function getTargetVersion(versions: string[], versionRange: strin
  * @returns `*` if the version is `undefined` or `latest", otherwise returns
  * the specified version.
  */
-export declare function resolveVersion(version?: Json): Json;
-/**
- * Checks whether a SemVer version range is valid.
- *
- * @param versionRange - A potential version range.
- * @returns `true` if the version range is valid, and `false` otherwise.
- */
-export declare function isValidSnapVersionRange(versionRange: unknown): versionRange is string;
+export declare function resolveVersionRange(version?: Json): [error: undefined, range: SemVerRange] | [error: Error, range: undefined];
+export {};

package/dist/versions.js

@@ -1,8 +1,63 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isValidSnapVersionRange = exports.resolveVersion = exports.getTargetVersion = exports.satisfiesVersionRange = exports.gtVersion = exports.DEFAULT_REQUESTED_SNAP_VERSION = void 0;
+exports.resolveVersionRange = exports.getTargetVersion = exports.satisfiesVersionRange = exports.gtVersion = exports.assertIsSemVerRange = exports.assertIsSemVerVersion = exports.isValidSemVerRange = exports.isValidSemVerVersion = exports.VersionRangeStruct = exports.VersionStruct = exports.DEFAULT_REQUESTED_SNAP_VERSION = void 0;
+const utils_1 = require("@metamask/utils");
 const semver_1 = require("semver");
+const superstruct_1 = require("superstruct");
 exports.DEFAULT_REQUESTED_SNAP_VERSION = '*';
+/**
+ * A struct for validating a version string.
+ */
+exports.VersionStruct = (0, superstruct_1.refine)((0, superstruct_1.string)(), 'Version', (value) => {
+    if ((0, semver_1.valid)(value) === null) {
+        return `Expected SemVer version, got "${value}"`;
+    }
+    return true;
+});
+exports.VersionRangeStruct = (0, superstruct_1.refine)((0, superstruct_1.string)(), 'Version range', (value) => {
+    if ((0, semver_1.validRange)(value) === null) {
+        return `Expected SemVer range, got "${value}"`;
+    }
+    return true;
+});
+/**
+ * Checks whether a SemVer version is valid.
+ *
+ * @param version - A potential version.
+ * @returns `true` if the version is valid, and `false` otherwise.
+ */
+function isValidSemVerVersion(version) {
+    return (0, superstruct_1.is)(version, exports.VersionStruct);
+}
+exports.isValidSemVerVersion = isValidSemVerVersion;
+/**
+ * Checks whether a SemVer version range is valid.
+ *
+ * @param versionRange - A potential version range.
+ * @returns `true` if the version range is valid, and `false` otherwise.
+ */
+function isValidSemVerRange(versionRange) {
+    return (0, superstruct_1.is)(versionRange, exports.VersionRangeStruct);
+}
+exports.isValidSemVerRange = isValidSemVerRange;
+/**
+ * Asserts that a value is a valid concrete SemVer version.
+ *
+ * @param version - A potential SemVer concrete version.
+ */
+function assertIsSemVerVersion(version) {
+    (0, utils_1.assertStruct)(version, exports.VersionStruct);
+}
+exports.assertIsSemVerVersion = assertIsSemVerVersion;
+/**
+ * Asserts that a value is a valid SemVer range.
+ *
+ * @param range - A potential SemVer range.
+ */
+function assertIsSemVerRange(range) {
+    (0, utils_1.assertStruct)(range, exports.VersionRangeStruct);
+}
+exports.assertIsSemVerRange = assertIsSemVerRange;
 /**
  * Checks whether a SemVer version is greater than another.
  *
@@ -11,7 +66,7 @@ exports.DEFAULT_REQUESTED_SNAP_VERSION = '*';
  * @returns `version1 > version2`.
  */
 function gtVersion(version1, version2) {
-    return (0, semver_1.gt)(version1, version2, { includePrerelease: true });
+    return (0, semver_1.gt)(version1, version2);
 }
 exports.gtVersion = gtVersion;
 /**
@@ -56,22 +111,11 @@ exports.getTargetVersion = getTargetVersion;
  * @returns `*` if the version is `undefined` or `latest", otherwise returns
  * the specified version.
  */
-function resolveVersion(version) {
+function resolveVersionRange(version) {
     if (version === undefined || version === 'latest') {
-        return exports.DEFAULT_REQUESTED_SNAP_VERSION;
+        return [undefined, exports.DEFAULT_REQUESTED_SNAP_VERSION];
     }
-    return version;
-}
-exports.resolveVersion = resolveVersion;
-/**
- * Checks whether a SemVer version range is valid.
- *
- * @param versionRange - A potential version range.
- * @returns `true` if the version range is valid, and `false` otherwise.
- */
-function isValidSnapVersionRange(versionRange) {
-    return Boolean(typeof versionRange === 'string' &&
-        (0, semver_1.validRange)(versionRange, { includePrerelease: true }) !== null);
+    return (0, superstruct_1.validate)(version, exports.VersionRangeStruct);
 }
-exports.isValidSnapVersionRange = isValidSnapVersionRange;
+exports.resolveVersionRange = resolveVersionRange;
 //# sourceMappingURL=versions.js.map

package/dist/versions.js.map

@@ -1 +1 @@
-{"version":3,"file":"versions.js","sourceRoot":"","sources":["../src/versions.ts"],"names":[],"mappings":";;;AACA,mCAKgB;AAEH,QAAA,8BAA8B,GAAG,GAAG,CAAC;AAElD;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,QAAgB,EAAE,QAAgB;IAC1D,OAAO,IAAA,WAAQ,EAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;AACnE,CAAC;AAFD,8BAEC;AAED;;;;;;GAMG;AACH,SAAgB,qBAAqB,CACnC,OAAe,EACf,YAAoB;IAEpB,OAAO,IAAA,kBAAe,EAAC,OAAO,EAAE,YAAY,EAAE;QAC5C,iBAAiB,EAAE,IAAI;KACxB,CAAC,CAAC;AACL,CAAC;AAPD,sDAOC;AAED;;;;;;;;;GASG;AACH,SAAgB,gBAAgB,CAC9B,QAAkB,EAClB,YAAoB;IAEpB,MAAM,0BAA0B,GAAG,IAAA,sBAAmB,EACpD,QAAQ,EACR,YAAY,CACb,CAAC;IAEF,4CAA4C;IAC5C,IAAI,0BAA0B,EAAE;QAC9B,OAAO,0BAA0B,CAAC;KACnC;IAED,iFAAiF;IACjF,OAAO,IAAA,sBAAmB,EAAC,QAAQ,EAAE,YAAY,EAAE;QACjD,iBAAiB,EAAE,IAAI;KACxB,CAAC,CAAC;AACL,CAAC;AAlBD,4CAkBC;AAED;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,OAAc;IAC3C,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,QAAQ,EAAE;QACjD,OAAO,sCAA8B,CAAC;KACvC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AALD,wCAKC;AAED;;;;;GAKG;AACH,SAAgB,uBAAuB,CACrC,YAAqB;IAErB,OAAO,OAAO,CACZ,OAAO,YAAY,KAAK,QAAQ;QAC9B,IAAA,mBAAgB,EAAC,YAAY,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CACvE,CAAC;AACJ,CAAC;AAPD,0DAOC","sourcesContent":["import { Json } from '@metamask/utils';\nimport {\n  gt as gtSemver,\n  maxSatisfying as maxSatisfyingSemver,\n  satisfies as satisfiesSemver,\n  validRange as validRangeSemver,\n} from 'semver';\n\nexport const DEFAULT_REQUESTED_SNAP_VERSION = '*';\n\n/**\n * Checks whether a SemVer version is greater than another.\n *\n * @param version1 - The left-hand version.\n * @param version2 - The right-hand version.\n * @returns `version1 > version2`.\n */\nexport function gtVersion(version1: string, version2: string): boolean {\n  return gtSemver(version1, version2, { includePrerelease: true });\n}\n\n/**\n * Returns whether a SemVer version satisfies a SemVer range.\n *\n * @param version - The SemVer version to check.\n * @param versionRange - The SemVer version range to check against.\n * @returns Whether the version satisfied the version range.\n */\nexport function satisfiesVersionRange(\n  version: string,\n  versionRange: string,\n): boolean {\n  return satisfiesSemver(version, versionRange, {\n    includePrerelease: true,\n  });\n}\n\n/**\n * Return the highest version in the list that satisfies the range, or `null` if\n * none of them do. For the satisfaction check, pre-release versions will only\n * be checked if no satisfactory non-prerelease version is found first.\n *\n * @param versions - The list of version to check.\n * @param versionRange - The SemVer version range to check against.\n * @returns The highest version in the list that satisfies the range,\n * or `null` if none of them do.\n */\nexport function getTargetVersion(\n  versions: string[],\n  versionRange: string,\n): string | null {\n  const maxSatisfyingNonPreRelease = maxSatisfyingSemver(\n    versions,\n    versionRange,\n  );\n\n  // By default don't use pre-release versions\n  if (maxSatisfyingNonPreRelease) {\n    return maxSatisfyingNonPreRelease;\n  }\n\n  // If no satisfying release version is found by default, try pre-release versions\n  return maxSatisfyingSemver(versions, versionRange, {\n    includePrerelease: true,\n  });\n}\n\n/**\n * Parse a version received by some subject attempting to access a snap.\n *\n * @param version - The received version value.\n * @returns `*` if the version is `undefined` or `latest\", otherwise returns\n * the specified version.\n */\nexport function resolveVersion(version?: Json): Json {\n  if (version === undefined || version === 'latest') {\n    return DEFAULT_REQUESTED_SNAP_VERSION;\n  }\n  return version;\n}\n\n/**\n * Checks whether a SemVer version range is valid.\n *\n * @param versionRange - A potential version range.\n * @returns `true` if the version range is valid, and `false` otherwise.\n */\nexport function isValidSnapVersionRange(\n  versionRange: unknown,\n): versionRange is string {\n  return Boolean(\n    typeof versionRange === 'string' &&\n      validRangeSemver(versionRange, { includePrerelease: true }) !== null,\n  );\n}\n"]}
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../src/versions.ts"],"names":[],"mappings":";;;AAAA,2CAAqD;AACrD,mCAMgB;AAChB,6CAAmE;AAItD,QAAA,8BAA8B,GAAG,GAAkB,CAAC;AA8CjE;;GAEG;AACU,QAAA,aAAa,GAAG,IAAA,oBAAM,EACjC,IAAA,oBAAM,GAA4C,EAClD,SAAS,EACT,CAAC,KAAK,EAAE,EAAE;IACR,IAAI,IAAA,cAAkB,EAAC,KAAK,CAAC,KAAK,IAAI,EAAE;QACtC,OAAO,iCAAiC,KAAK,GAAG,CAAC;KAClD;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CACF,CAAC;AAEW,QAAA,kBAAkB,GAAG,IAAA,oBAAM,EACtC,IAAA,oBAAM,GAA0C,EAChD,eAAe,EACf,CAAC,KAAK,EAAE,EAAE;IACR,IAAI,IAAA,mBAAgB,EAAC,KAAK,CAAC,KAAK,IAAI,EAAE;QACpC,OAAO,+BAA+B,KAAK,GAAG,CAAC;KAChD;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CACF,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,oBAAoB,CAClC,OAAgB;IAEhB,OAAO,IAAA,gBAAE,EAAC,OAAO,EAAE,qBAAa,CAAC,CAAC;AACpC,CAAC;AAJD,oDAIC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB,CAChC,YAAqB;IAErB,OAAO,IAAA,gBAAE,EAAC,YAAY,EAAE,0BAAkB,CAAC,CAAC;AAC9C,CAAC;AAJD,gDAIC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB,CACnC,OAAgB;IAEhB,IAAA,oBAAY,EAAC,OAAO,EAAE,qBAAa,CAAC,CAAC;AACvC,CAAC;AAJD,sDAIC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB,CACjC,KAAc;IAEd,IAAA,oBAAY,EAAC,KAAK,EAAE,0BAAkB,CAAC,CAAC;AAC1C,CAAC;AAJD,kDAIC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CACvB,QAAuB,EACvB,QAAuB;IAEvB,OAAO,IAAA,WAAQ,EAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACtC,CAAC;AALD,8BAKC;AAED;;;;;;GAMG;AACH,SAAgB,qBAAqB,CACnC,OAAsB,EACtB,YAAyB;IAEzB,OAAO,IAAA,kBAAe,EAAC,OAAO,EAAE,YAAY,EAAE;QAC5C,iBAAiB,EAAE,IAAI;KACxB,CAAC,CAAC;AACL,CAAC;AAPD,sDAOC;AAED;;;;;;;;;GASG;AACH,SAAgB,gBAAgB,CAC9B,QAAyB,EACzB,YAAyB;IAEzB,MAAM,0BAA0B,GAAG,IAAA,sBAAmB,EACpD,QAAQ,EACR,YAAY,CACb,CAAC;IAEF,4CAA4C;IAC5C,IAAI,0BAA0B,EAAE;QAC9B,OAAO,0BAA0B,CAAC;KACnC;IAED,iFAAiF;IACjF,OAAO,IAAA,sBAAmB,EAAC,QAAQ,EAAE,YAAY,EAAE;QACjD,iBAAiB,EAAE,IAAI;KACxB,CAAC,CAAC;AACL,CAAC;AAlBD,4CAkBC;AAED;;;;;;GAMG;AACH,SAAgB,mBAAmB,CACjC,OAAc;IAEd,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,QAAQ,EAAE;QACjD,OAAO,CAAC,SAAS,EAAE,sCAA8B,CAAC,CAAC;KACpD;IACD,OAAO,IAAA,sBAAQ,EAAC,OAAO,EAAE,0BAAkB,CAAC,CAAC;AAC/C,CAAC;AAPD,kDAOC","sourcesContent":["import { assertStruct, Json } from '@metamask/utils';\nimport {\n  gt as gtSemver,\n  maxSatisfying as maxSatisfyingSemver,\n  satisfies as satisfiesSemver,\n  valid as validSemVerVersion,\n  validRange as validSemVerRange,\n} from 'semver';\nimport { is, refine, string, Struct, validate } from 'superstruct';\n\nimport { Opaque } from './types';\n\nexport const DEFAULT_REQUESTED_SNAP_VERSION = '*' as SemVerRange;\n\n/**\n * {@link https://codemix.com/opaque-types-in-javascript/ Opaque} type for SemVer ranges.\n *\n * @example Use {@link assertIsSemVerRange} and {@link isValidSemVerRange} to cast to proper type.\n * ```typescript\n * const unsafeRange: string = dataFromUser();\n * assertIsSemVerRange(unsafeRange);\n * unsafeRange\n * // ^? SemVerRange\n * ```\n * @example If you know what you're doing and want to side-step type safety, casting from a string works correctly.\n * ```typescript\n * const unsafeRange: string = dataFromUser();\n * unsafeRange as SemVerRange;\n * // ^? SemVerRange\n * ```\n * @see {@link assertIsSemVerRange}\n * @see {@link isValidSemVerRange}\n */\nexport type SemVerRange = Opaque<string, typeof semVerRange>;\ndeclare const semVerRange: unique symbol;\n\n/**\n * {@link https://codemix.com/opaque-types-in-javascript/ Opaque} type for singular SemVer version.\n *\n * @example Use {@link assertIsSemVerVersion} and {@link isValidSemVerVersion} to cast to proper type.\n * ```typescript\n * const unsafeVersion: string = dataFromUser();\n * assertIsSemVerVersion(unsafeRange);\n * unsafeVersion\n * // ^? SemVerVersion\n * ```\n * @example If you know what you're doing and want to side-step type safety, casting from a string works correctly.\n * ```typescript\n * const unsafeVersion: string = dataFromUser();\n * unsafeRange as SemVerVersion;\n * // ^? SemVerVersion\n * ```\n * @see {@link assertIsSemVerVersion}\n * @see {@link isValidSemVerVersion}\n */\nexport type SemVerVersion = Opaque<string, typeof semVerVersion>;\ndeclare const semVerVersion: unique symbol;\n\n/**\n * A struct for validating a version string.\n */\nexport const VersionStruct = refine<SemVerVersion, null>(\n  string() as unknown as Struct<SemVerVersion, null>,\n  'Version',\n  (value) => {\n    if (validSemVerVersion(value) === null) {\n      return `Expected SemVer version, got \"${value}\"`;\n    }\n    return true;\n  },\n);\n\nexport const VersionRangeStruct = refine<SemVerRange, null>(\n  string() as unknown as Struct<SemVerRange, null>,\n  'Version range',\n  (value) => {\n    if (validSemVerRange(value) === null) {\n      return `Expected SemVer range, got \"${value}\"`;\n    }\n    return true;\n  },\n);\n\n/**\n * Checks whether a SemVer version is valid.\n *\n * @param version - A potential version.\n * @returns `true` if the version is valid, and `false` otherwise.\n */\nexport function isValidSemVerVersion(\n  version: unknown,\n): version is SemVerVersion {\n  return is(version, VersionStruct);\n}\n\n/**\n * Checks whether a SemVer version range is valid.\n *\n * @param versionRange - A potential version range.\n * @returns `true` if the version range is valid, and `false` otherwise.\n */\nexport function isValidSemVerRange(\n  versionRange: unknown,\n): versionRange is SemVerRange {\n  return is(versionRange, VersionRangeStruct);\n}\n\n/**\n * Asserts that a value is a valid concrete SemVer version.\n *\n * @param version - A potential SemVer concrete version.\n */\nexport function assertIsSemVerVersion(\n  version: unknown,\n): asserts version is SemVerVersion {\n  assertStruct(version, VersionStruct);\n}\n\n/**\n * Asserts that a value is a valid SemVer range.\n *\n * @param range - A potential SemVer range.\n */\nexport function assertIsSemVerRange(\n  range: unknown,\n): asserts range is SemVerRange {\n  assertStruct(range, VersionRangeStruct);\n}\n\n/**\n * Checks whether a SemVer version is greater than another.\n *\n * @param version1 - The left-hand version.\n * @param version2 - The right-hand version.\n * @returns `version1 > version2`.\n */\nexport function gtVersion(\n  version1: SemVerVersion,\n  version2: SemVerVersion,\n): boolean {\n  return gtSemver(version1, version2);\n}\n\n/**\n * Returns whether a SemVer version satisfies a SemVer range.\n *\n * @param version - The SemVer version to check.\n * @param versionRange - The SemVer version range to check against.\n * @returns Whether the version satisfied the version range.\n */\nexport function satisfiesVersionRange(\n  version: SemVerVersion,\n  versionRange: SemVerRange,\n): boolean {\n  return satisfiesSemver(version, versionRange, {\n    includePrerelease: true,\n  });\n}\n\n/**\n * Return the highest version in the list that satisfies the range, or `null` if\n * none of them do. For the satisfaction check, pre-release versions will only\n * be checked if no satisfactory non-prerelease version is found first.\n *\n * @param versions - The list of version to check.\n * @param versionRange - The SemVer version range to check against.\n * @returns The highest version in the list that satisfies the range,\n * or `null` if none of them do.\n */\nexport function getTargetVersion(\n  versions: SemVerVersion[],\n  versionRange: SemVerRange,\n): SemVerVersion | null {\n  const maxSatisfyingNonPreRelease = maxSatisfyingSemver(\n    versions,\n    versionRange,\n  );\n\n  // By default don't use pre-release versions\n  if (maxSatisfyingNonPreRelease) {\n    return maxSatisfyingNonPreRelease;\n  }\n\n  // If no satisfying release version is found by default, try pre-release versions\n  return maxSatisfyingSemver(versions, versionRange, {\n    includePrerelease: true,\n  });\n}\n\n/**\n * Parse a version received by some subject attempting to access a snap.\n *\n * @param version - The received version value.\n * @returns `*` if the version is `undefined` or `latest\", otherwise returns\n * the specified version.\n */\nexport function resolveVersionRange(\n  version?: Json,\n): [error: undefined, range: SemVerRange] | [error: Error, range: undefined] {\n  if (version === undefined || version === 'latest') {\n    return [undefined, DEFAULT_REQUESTED_SNAP_VERSION];\n  }\n  return validate(version, VersionRangeStruct);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamask/snaps-utils",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/MetaMask/snaps-monorepo.git"
@@ -52,7 +52,7 @@
   "dependencies": {
     "@babel/core": "^7.18.6",
     "@babel/types": "^7.18.7",
-    "@metamask/snaps-types": "^0.24.0",
+    "@metamask/snaps-types": "^0.25.0",
     "@metamask/utils": "^3.3.1",
     "@noble/hashes": "^1.1.3",
     "@scure/base": "^1.1.1",
@@ -66,29 +66,31 @@
   },
   "devDependencies": {
     "@lavamoat/allow-scripts": "^2.0.3",
-    "@metamask/auto-changelog": "^2.6.0",
-    "@metamask/eslint-config": "^9.0.0",
-    "@metamask/eslint-config-jest": "^9.0.0",
-    "@metamask/eslint-config-nodejs": "^9.0.0",
-    "@metamask/eslint-config-typescript": "^9.0.1",
+    "@metamask/auto-changelog": "^3.1.0",
+    "@metamask/eslint-config": "^11.0.0",
+    "@metamask/eslint-config-jest": "^11.0.0",
+    "@metamask/eslint-config-nodejs": "^11.0.1",
+    "@metamask/eslint-config-typescript": "^11.0.0",
     "@types/jest": "^27.5.1",
     "@types/semver": "^7.3.10",
+    "@typescript-eslint/eslint-plugin": "^5.42.1",
+    "@typescript-eslint/parser": "^5.42.1",
     "deepmerge": "^4.2.2",
-    "eslint": "^7.30.0",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-import": "^2.23.4",
-    "eslint-plugin-jest": "^24.4.0",
-    "eslint-plugin-jsdoc": "^36.1.0",
+    "eslint": "^8.27.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-jest": "^27.1.5",
+    "eslint-plugin-jsdoc": "^39.6.2",
     "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-prettier": "^3.4.0",
+    "eslint-plugin-prettier": "^4.2.1",
     "jest": "^29.0.2",
     "jest-it-up": "^2.0.0",
     "memfs": "^3.4.7",
-    "prettier": "^2.3.2",
+    "prettier": "^2.7.1",
     "prettier-plugin-packagejson": "^2.2.11",
     "rimraf": "^3.0.2",
     "ts-jest": "^29.0.0",
-    "typescript": "^4.4.0"
+    "typescript": "~4.8.4"
   },
   "engines": {
     "node": ">=16.0.0"