@endo/compartment-mapper 1.6.2 → 2.0.0

package/src/types/policy-schema.ts

@@ -5,6 +5,8 @@
  * @module
  */
 
+import type { WILDCARD_POLICY_VALUE } from '../policy-format.js';
+
 /* eslint-disable no-use-before-define */
 
 /**
@@ -14,7 +16,7 @@ export type FullAttenuationDefinition = {
   /** The type of attenuation. */
   attenuate: string;
   /** The parameters for the attenuation. */
-  params: ImplicitAttenuationDefinition;
+  params?: ImplicitAttenuationDefinition;
 };
 
 /**
@@ -38,7 +40,7 @@ export type UnifiedAttenuationDefinition = {
 /**
  * A type representing a wildcard policy, which can be 'any'.
  */
-export type WildcardPolicy = 'any';
+export type WildcardPolicy = typeof WILDCARD_POLICY_VALUE;
 
 /**
  * A type representing a property policy, which is a record of string keys and
@@ -51,7 +53,9 @@ export type PropertyPolicy = Record<string, boolean>;
  * wildcard policy}, a property policy, `undefined`, or defined by an
  * attenuator
  */
-export type PolicyItem<T = void> = WildcardPolicy | PropertyPolicy | T;
+export type PolicyItem<T = void> = [T] extends [void]
+  ? WildcardPolicy | PropertyPolicy
+  : WildcardPolicy | PropertyPolicy | T;
 
 /**
  * An object representing a nested attenuation definition.
@@ -70,22 +74,36 @@ export type PackagePolicy<
   BuiltinsPolicyItem = void,
   ExtraOptions = unknown,
 > = {
-  /** The default attenuator. */
+  /**
+   * The default attenuator, if any.
+   */
   defaultAttenuator?: string | undefined;
-  /** The policy item for packages. */
+  /**
+   * The policy item for packages.
+   */
   packages?: PolicyItem<PackagePolicyItem> | undefined;
-  /** The policy item or full attenuation definition for globals. */
+  /**
+   * The policy item or full attenuation definition for globals.
+   */
   globals?: AttenuationDefinition | PolicyItem<GlobalsPolicyItem> | undefined;
-  /** The policy item or nested attenuation definition for builtins. */
+  /**
+   * The policy item or nested attenuation definition for builtins.
+   */
   builtins?:
     | NestedAttenuationDefinition
     | PolicyItem<BuiltinsPolicyItem>
     | undefined;
-  /** Whether to disable global freeze. */
+  /**
+   * Whether to disable global freeze.
+   */
   noGlobalFreeze?: boolean | undefined;
-  /** Whether to allow dynamic imports */
+  /**
+   * Whether to allow dynamic imports
+   */
   dynamic?: boolean | undefined;
-  /** Any additional user-defined options can be added to the policy here */
+  /**
+   * Any additional user-defined options can be added to the policy here
+   */
   options?: ExtraOptions | undefined;
 };
 
@@ -125,9 +143,4 @@ export type Policy<
 export type SomePolicy = Policy<any, any, any, any>;
 
 /** Any {@link PackagePolicy} */
-export type SomePackagePolicy = PackagePolicy<
-  PolicyItem,
-  PolicyItem,
-  PolicyItem,
-  unknown
->;
+export type SomePackagePolicy = PackagePolicy<void, void, void, unknown>;

package/src/types/policy.d.ts

@@ -3,11 +3,11 @@
  *
  * @module
  */
-import type { SomeObject } from './typescript.js';
+import type { LiteralUnion, SomeObject } from './typescript.js';
 export type PackageNamingKit = {
     /** true if location is the entry compartment */
     isEntry?: boolean | undefined;
-    name: string;
+    name?: LiteralUnion<'<ATTENUATORS>', string>;
     path: Array<string>;
 };
 export type Attenuator<GlobalParams extends [any, ...any[]] = [any, ...any[]], ModuleParams extends [any, ...any[]] = [any, ...any[]]> = {
@@ -19,4 +19,8 @@ export type ModuleAttenuatorFn<Params extends [any, ...any[]] = [any, ...any[]],
 export type DeferredAttenuatorsProvider = {
     import: (attenuatorSpecifier: string | null) => Promise<Attenuator>;
 };
+/**
+ * A fieldname of `PackagePolicy`; used with `policyLookupHelper()`
+ */
+export type PolicyEnforcementField = 'builtins' | 'globals' | 'packages';
 //# sourceMappingURL=policy.d.ts.map

package/src/types/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["policy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,UAAU,CACpB,YAAY,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,EACtD,YAAY,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,IACpD;IACF,gBAAgB,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC;IAChE,eAAe,CAAC,EACZ,kBAAkB,CAAC,YAAY,EAAE,UAAU,EAAE,UAAU,CAAC,GACxD,SAAS,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAC5B,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,IAC9C,CACF,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,EACxC,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,KACjC,IAAI,CAAC;AAEV,MAAM,MAAM,kBAAkB,CAC5B,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,EAChD,CAAC,GAAG,UAAU,EACd,CAAC,GAAG,CAAC,IACH,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;AAEjC,MAAM,MAAM,2BAA2B,GAAG;IACxC,MAAM,EAAE,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACrE,CAAC"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["policy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEhE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,IAAI,CAAC,EAAE,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAC7C,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,UAAU,CACpB,YAAY,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,EACtD,YAAY,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,IACpD;IACF,gBAAgB,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC;IAChE,eAAe,CAAC,EACZ,kBAAkB,CAAC,YAAY,EAAE,UAAU,EAAE,UAAU,CAAC,GACxD,SAAS,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAC5B,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,IAC9C,CACF,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,EACxC,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,KACjC,IAAI,CAAC;AAEV,MAAM,MAAM,kBAAkB,CAC5B,MAAM,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,EAChD,CAAC,GAAG,UAAU,EACd,CAAC,GAAG,CAAC,IACH,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;AAEjC,MAAM,MAAM,2BAA2B,GAAG;IACxC,MAAM,EAAE,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACrE,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC"}

package/src/types/policy.ts

@@ -6,12 +6,12 @@
 
 /* eslint-disable no-use-before-define */
 
-import type { SomeObject } from './typescript.js';
+import type { LiteralUnion, SomeObject } from './typescript.js';
 
 export type PackageNamingKit = {
   /** true if location is the entry compartment */
   isEntry?: boolean | undefined;
-  name: string;
+  name?: LiteralUnion<'<ATTENUATORS>', string>;
   path: Array<string>;
 };
 
@@ -42,3 +42,8 @@ export type ModuleAttenuatorFn<
 export type DeferredAttenuatorsProvider = {
   import: (attenuatorSpecifier: string | null) => Promise<Attenuator>;
 };
+
+/**
+ * A fieldname of `PackagePolicy`; used with `policyLookupHelper()`
+ */
+export type PolicyEnforcementField = 'builtins' | 'globals' | 'packages';

package/src/types/powers.d.ts

@@ -7,8 +7,13 @@
  * @module
  */
 import type { SomeObject } from './typescript.js';
-export type ReadPowers = {
-    canonical: CanonicalFn;
+/**
+ * All available read powers
+ *
+ * @template T The expected input/output type of the {@link CanonicalFn}.
+ */
+export type ReadPowers<T extends string = any> = {
+    canonical: CanonicalFn<T>;
     read: ReadFn;
     maybeRead?: MaybeReadFn;
     readNow?: ReadNowFn;
@@ -19,7 +24,10 @@ export type ReadPowers = {
     requireResolve?: RequireResolveFn;
     isAbsolute?: IsAbsoluteFn;
 };
-export type MaybeReadPowers = ReadPowers & {
+/**
+ * @template T The expected input/output type of the {@link CanonicalFn}.
+ */
+export type MaybeReadPowers<T extends string = any> = ReadPowers<T> & {
     maybeRead: MaybeReadFn;
 };
 /**
@@ -31,31 +39,45 @@ export type MaybeReadPowers = ReadPowers & {
  * 2. Prop `maybeReadNow` is a function
  * 3. Prop `fileURLToPath` is a function
  * 4. Prop `isAbsolute` is a function
+ *
+ * @template T The expected input/output type of the {@link CanonicalFn}.
  */
-export type ReadNowPowers = Omit<ReadPowers, ReadNowPowersProp> & Required<Pick<ReadPowers, ReadNowPowersProp>>;
+export type ReadNowPowers<T extends string = any> = Omit<ReadPowers<T>, ReadNowPowersProp> & Required<Pick<ReadPowers<T>, ReadNowPowersProp>>;
 /**
  * These properties are necessary for dynamic require support
  */
 export type ReadNowPowersProp = 'fileURLToPath' | 'isAbsolute' | 'maybeReadNow';
 /**
  * Returns a canonical URL for a given URL, following redirects or symbolic
- * links if any exist along the path.
- * Must return the given logical location if the real location does not exist.
+ * links if any exist along the path. Must return the given logical location if
+ * the real location does not exist.
+ *
+ * @template T The expected input/output type of the {@link CanonicalFn}. This
+ * may be a particular type of URL, such as a `FileUrlString`.
+ */
+export type CanonicalFn<T extends string = string> = (location: T) => Promise<T>;
+/**
+ * A function which reads some location and resolves with bytes.
  */
-export type CanonicalFn = (location: string) => Promise<string>;
 export type ReadFn = (location: string) => Promise<Uint8Array>;
 /**
  * A resolution of `undefined` indicates `ENOENT` or the equivalent.
  */
 export type MaybeReadFn = (location: string) => Promise<Uint8Array | undefined>;
+/**
+ * A function which reads some location and returns bytes.
+ */
 export type ReadNowFn = (location: string) => Uint8Array;
 /**
  * A resolution of `undefined` indicates `ENOENT` or the equivalent.
  */
 export type MaybeReadNowFn = (location: string) => Uint8Array | undefined;
+/**
+ * Returns a string hash of a byte array
+ */
 export type HashFn = (bytes: Uint8Array) => string;
-export type FileURLToPathFn = typeof import('node:url').fileURLToPath;
-export type PathToFileURLFn = typeof import('node:url').pathToFileURL;
+export type FileURLToPathFn = (url: URL | string) => string;
+export type PathToFileURLFn = (path: string) => URL;
 export type RequireResolveFn = (fromLocation: string, specifier: string, options?: {
     paths?: string[];
 } | undefined) => any;
@@ -63,9 +85,14 @@ export type IsAbsoluteFn = (location: string) => boolean;
 export type ArchiveReader = {
     read: ReadFn;
 };
-export type HashPowers = {
+/**
+ * Read powers with a {@link HashFn}.
+ *
+ * @template T The expected input/output type of the {@link CanonicalFn}.
+ */
+export type HashPowers<T extends string = any> = {
     read: ReadFn;
-    canonical: CanonicalFn;
+    canonical: CanonicalFn<T>;
     computeSha512: HashFn;
 };
 export type WritePowers = {

package/src/types/powers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"powers.d.ts","sourceRoot":"","sources":["powers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"powers.d.ts","sourceRoot":"","sources":["powers.ts"],"names":[],"mappings":"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"}

package/src/types/powers.ts

@@ -11,10 +11,15 @@
 
 import type { SomeObject } from './typescript.js';
 
-// Read
+// #region read
 
-export type ReadPowers = {
-  canonical: CanonicalFn;
+/**
+ * All available read powers
+ *
+ * @template T The expected input/output type of the {@link CanonicalFn}.
+ */
+export type ReadPowers<T extends string = any> = {
+  canonical: CanonicalFn<T>;
   read: ReadFn;
   maybeRead?: MaybeReadFn;
   readNow?: ReadNowFn;
@@ -26,7 +31,10 @@ export type ReadPowers = {
   isAbsolute?: IsAbsoluteFn;
 };
 
-export type MaybeReadPowers = ReadPowers & {
+/**
+ * @template T The expected input/output type of the {@link CanonicalFn}.
+ */
+export type MaybeReadPowers<T extends string = any> = ReadPowers<T> & {
   maybeRead: MaybeReadFn;
 };
 
@@ -39,9 +47,14 @@ export type MaybeReadPowers = ReadPowers & {
  * 2. Prop `maybeReadNow` is a function
  * 3. Prop `fileURLToPath` is a function
  * 4. Prop `isAbsolute` is a function
+ *
+ * @template T The expected input/output type of the {@link CanonicalFn}.
  */
-export type ReadNowPowers = Omit<ReadPowers, ReadNowPowersProp> &
-  Required<Pick<ReadPowers, ReadNowPowersProp>>;
+export type ReadNowPowers<T extends string = any> = Omit<
+  ReadPowers<T>,
+  ReadNowPowersProp
+> &
+  Required<Pick<ReadPowers<T>, ReadNowPowersProp>>;
 
 /**
  * These properties are necessary for dynamic require support
@@ -50,11 +63,19 @@ export type ReadNowPowersProp = 'fileURLToPath' | 'isAbsolute' | 'maybeReadNow';
 
 /**
  * Returns a canonical URL for a given URL, following redirects or symbolic
- * links if any exist along the path.
- * Must return the given logical location if the real location does not exist.
+ * links if any exist along the path. Must return the given logical location if
+ * the real location does not exist.
+ *
+ * @template T The expected input/output type of the {@link CanonicalFn}. This
+ * may be a particular type of URL, such as a `FileUrlString`.
  */
-export type CanonicalFn = (location: string) => Promise<string>;
+export type CanonicalFn<T extends string = string> = (
+  location: T,
+) => Promise<T>;
 
+/**
+ * A function which reads some location and resolves with bytes.
+ */
 export type ReadFn = (location: string) => Promise<Uint8Array>;
 
 /**
@@ -62,6 +83,9 @@ export type ReadFn = (location: string) => Promise<Uint8Array>;
  */
 export type MaybeReadFn = (location: string) => Promise<Uint8Array | undefined>;
 
+/**
+ * A function which reads some location and returns bytes.
+ */
 export type ReadNowFn = (location: string) => Uint8Array;
 
 /**
@@ -69,11 +93,14 @@ export type ReadNowFn = (location: string) => Uint8Array;
  */
 export type MaybeReadNowFn = (location: string) => Uint8Array | undefined;
 
+/**
+ * Returns a string hash of a byte array
+ */
 export type HashFn = (bytes: Uint8Array) => string;
 
-export type FileURLToPathFn = typeof import('node:url').fileURLToPath;
+export type FileURLToPathFn = (url: URL | string) => string;
 
-export type PathToFileURLFn = typeof import('node:url').pathToFileURL;
+export type PathToFileURLFn = (path: string) => URL;
 
 export type RequireResolveFn = (
   fromLocation: string,
@@ -91,14 +118,19 @@ export type ArchiveReader = {
   read: ReadFn;
 };
 
-export type HashPowers = {
+/**
+ * Read powers with a {@link HashFn}.
+ *
+ * @template T The expected input/output type of the {@link CanonicalFn}.
+ */
+export type HashPowers<T extends string = any> = {
   read: ReadFn;
-  canonical: CanonicalFn;
+  canonical: CanonicalFn<T>;
   computeSha512: HashFn;
 };
+// #endregion
 
-// Write
-
+// #region write
 export type WritePowers = {
   write: WriteFn;
 };
@@ -111,12 +143,13 @@ export type ArchiveWriter = {
 };
 
 export type SnapshotFn = () => Promise<Uint8Array>;
+// #endregion
 
-// Execute
-
+// #region execute
 export type Application = {
   import: ExecuteFn;
   sha512?: string | undefined;
 };
 
 export type ExecuteFn = (options?: any) => Promise<SomeObject>;
+// #endregion

package/src/types/typescript.d.ts

@@ -25,6 +25,34 @@ export type Primitive = null | undefined | string | number | boolean | symbol |
  * https://github.com/Microsoft/TypeScript/issues/29729
  * Microsoft/TypeScript#29729}. It will be removed as soon as it's not needed
  * anymore.
+ * @see {@link https://www.npmjs.com/package/type-fest}
  */
 export type LiteralUnion<LiteralType, PrimitiveType extends Primitive> = LiteralType | (PrimitiveType & Record<never, never>);
+/**
+ * Generic type guard function that checks if a value of type `T` is also of type `U`.
+ * @template T The type of the value to check.
+ * @template U The type that the value should be checked against.
+ */
+export type TypeGuard<T, U extends T> = (value: T) => value is U;
+/**
+ * Helper type for a generic type guard used in an "extends" clause
+ */
+export type SomeTypeGuard = TypeGuard<any, any>;
+/**
+ * Infers the type that a type guard function checks for.
+ *
+ * @template T The type guard function type itself
+ * @returns The type that the guard checks for
+ */
+export type GuardedType<T> = T extends (value: any) => value is infer U ? U : never;
+/**
+ * Converts a union type to an intersection type
+ */
+export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Makes a nicer tooltip for `T` in IDEs (most of the time).
+ */
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
 //# sourceMappingURL=typescript.d.ts.map

package/src/types/typescript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["typescript.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,SAAS,GACT,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,GACN,MAAM,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,CAAC,WAAW,EAAE,aAAa,SAAS,SAAS,IACjE,WAAW,GACX,CAAC,aAAa,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC"}
+{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["typescript.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,SAAS,GACT,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,GACN,MAAM,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY,CAAC,WAAW,EAAE,aAAa,SAAS,SAAS,IACjE,WAAW,GACX,CAAC,aAAa,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAE3C;;;;GAIG;AAEH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,KAAK,KAAK,IAAI,MAAM,CAAC,GACnE,CAAC,GACD,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CACnC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CACvC,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,IAAI,GAC1B,CAAC,GACD,KAAK,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAC"}

package/src/types/typescript.ts

@@ -35,9 +35,45 @@ export type Primitive =
  * https://github.com/Microsoft/TypeScript/issues/29729
  * Microsoft/TypeScript#29729}. It will be removed as soon as it's not needed
  * anymore.
+ * @see {@link https://www.npmjs.com/package/type-fest}
  */
 export type LiteralUnion<LiteralType, PrimitiveType extends Primitive> =
   | LiteralType
   | (PrimitiveType & Record<never, never>);
 
-// LiteralUnion is from https://www.npmjs.com/package/type-fest
+/**
+ * Generic type guard function that checks if a value of type `T` is also of type `U`.
+ * @template T The type of the value to check.
+ * @template U The type that the value should be checked against.
+ */
+
+export type TypeGuard<T, U extends T> = (value: T) => value is U;
+
+/**
+ * Helper type for a generic type guard used in an "extends" clause
+ */
+export type SomeTypeGuard = TypeGuard<any, any>;
+
+/**
+ * Infers the type that a type guard function checks for.
+ *
+ * @template T The type guard function type itself
+ * @returns The type that the guard checks for
+ */
+export type GuardedType<T> = T extends (value: any) => value is infer U
+  ? U
+  : never;
+
+/**
+ * Converts a union type to an intersection type
+ */
+export type UnionToIntersection<U> = (
+  U extends any ? (k: U) => void : never
+) extends (k: infer I) => void
+  ? I
+  : never;
+
+/**
+ * Makes a nicer tooltip for `T` in IDEs (most of the time).
+ */
+export type Simplify<T> = { [K in keyof T]: T[K] } & {};