@solana/nominal-types 6.3.1 → 6.3.2-canary-20260313112147

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@solana/nominal-types",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Type utilties for creating nominal/branded types in TypeScript",
   "homepage": "https://www.solanakit.com/api#solananominal-types",
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [

package/src/index.ts

@@ -0,0 +1,142 @@
+/**
+ * This package contains type utilities for creating nominal types in TypeScript.
+ *
+ * @example Brands, compression, and encodings can be combined
+ * ```ts
+ * const encodedCompressedString = 'abc' as Brand<
+ *     EncodedString<CompressedData<'abc', 'zstd'>, 'base64'>,
+ *     'Base64ZstdCompressedData'
+ * >;
+ *
+ * encodedCompressedString satisfies Brand<'abc', 'Base64ZstdCompressedData'>; // OK
+ * encodedCompressedString satisfies Brand<string, 'Base64ZstdCompressedData'>; // OK
+ * encodedCompressedString satisfies CompressedData<'abc', 'zstd'>; // OK
+ * encodedCompressedString satisfies CompressedData<string, 'zstd'>; // OK
+ * encodedCompressedString satisfies EncodedString<'abc', 'base64'>; // OK
+ * encodedCompressedString satisfies EncodedString<string, 'base64'>; // OK
+ * encodedCompressedString satisfies EncodedString<string, 'base58'>; // ERROR
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+type AffinePointValidity = 'invalid' | 'valid';
+type CompressionFormat = 'zstd';
+type StringEncoding = 'base58' | 'base64';
+
+/**
+ * Use this to produce a new type that satisfies the original type, but adds extra type information
+ * that marks the type as being an affine point over a field that either lies on a given curve
+ * (is valid) or does not (is invalid).
+ *
+ * @typeParam T - The underlying type
+ * @typeParam TValidity - Whether the point is valid or invalid
+ *
+ * @example
+ * ```ts
+ * const address = 'dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92';
+ * const onCurveAddress = address as AffinePoint<typeof address, 'valid'>;
+ *
+ * onCurveAddress satisfies AffinePoint<'dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92', 'valid'>; // OK
+ * onCurveAddress satisfies AffinePoint<string, 'valid'>; // OK
+ * onCurveAddress satisfies AffinePoint<string, 'invalid'>; // ERROR
+ * address satisfies AffinePoint<string, 'valid'>; // ERROR
+ * address satisfies AffinePoint<string, 'invalid'>; // ERROR
+ * ```
+ */
+export type AffinePoint<T, TValidity extends AffinePointValidity> = NominalType<'affinePoint', TValidity> & T;
+
+/**
+ * Use this to produce a new type that satisfies the original type, but not the other way around.
+ * That is to say, the branded type is acceptable wherever the original type is specified, but
+ * wherever the branded type is specified, the original type will be insufficient.
+ *
+ * You can use this to create specialized instances of strings, numbers, objects, and more which
+ * you would like to assert are special in some way (eg. numbers that are non-negative, strings
+ * which represent the names of foods, objects that have passed validation).
+ *
+ * @typeParam T - The base type to brand
+ * @typeParam TBrandName - A string that identifies a particular brand. Branded types with identical
+ * names will satisfy each other so long as their base types satisfy each other. Branded types with
+ * different names will never satisfy each other.
+ *
+ * @example
+ * ```ts
+ * const unverifiedName = 'Alice';
+ * const verifiedName = unverifiedName as Brand<'Alice', 'VerifiedName'>;
+ *
+ * 'Alice' satisfies Brand<string, 'VerifiedName'>; // ERROR
+ * 'Alice' satisfies Brand<'Alice', 'VerifiedName'>; // ERROR
+ * unverifiedName satisfies Brand<string, 'VerifiedName'>; // ERROR
+ * verifiedName satisfies Brand<'Bob', 'VerifiedName'>; // ERROR
+ * verifiedName satisfies Brand<'Alice', 'VerifiedName'>; // OK
+ * verifiedName satisfies Brand<string, 'VerifiedName'>; // OK
+ * ```
+ */
+export type Brand<T, TBrandName extends string> = NominalType<'brand', TBrandName> & T;
+
+/**
+ * Use this to produce a new type that satisfies the original type, but adds extra type information
+ * that marks the type as containing compressed data.
+ *
+ * @typeParam T - The base type to mark as representing compressed data
+ * @typeParam TFormat - The compression format of the underlying data
+ *
+ * @example
+ * ```ts
+ * const untaggedData = new Uint8Array([/* ... *\/]);
+ * const compressedData = untaggedData as CompressedData<typeof untaggedData, 'zstd'>;
+ *
+ * compressedData satisfies CompressedData<Uint8Array, 'zstd'>; // OK
+ * untaggedData satisfies CompressedData<Uint8Array, 'zstd'>; // ERROR
+ * ```
+ */
+export type CompressedData<T, TFormat extends CompressionFormat> = NominalType<'compressionFormat', TFormat> & T;
+
+/**
+ * Use this to produce a new type that satisfies the original string type, but adds extra type
+ * information that marks the string as being encoded in a particular format.
+ *
+ * @typeParam T - The underlying string type
+ * @typeParam TEncoding - The encoding format of the string
+ *
+ * @example
+ * ```ts
+ * const untaggedString = 'dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92';
+ * const encodedString = untaggedString as EncodedString<typeof untaggedString, 'base58'>;
+ *
+ * encodedString satisfies EncodedString<'dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92', 'base58'>; // OK
+ * encodedString satisfies EncodedString<string, 'base58'>; // OK
+ * encodedString satisfies EncodedString<string, 'base64'>; // ERROR
+ * untaggedString satisfies EncodedString<string, 'base58'>; // ERROR
+ * ```
+ */
+export type EncodedString<T extends string, TEncoding extends StringEncoding> = NominalType<
+    'stringEncoding',
+    TEncoding
+> &
+    T;
+
+/**
+ * Use this to produce a nominal type.
+ *
+ * This can be intersected with other base types to produce custom branded types.
+ *
+ * @typeParam TKey - The name of the nominal type. This distinguishes one nominal type from another.
+ * @typeParam TMarker - The type of the value the nominal type can take.
+ *
+ * @example
+ * ```ts
+ * type SweeteningSubstance = 'aspartame' | 'cane-sugar' | 'stevia';
+ * type Sweetener<T extends SweeteningSubstance> = NominalType<'sweetener', T>;
+ *
+ * // This function accepts sweetened foods, except those with aspartame.
+ * declare function eat(food: string & Sweetener<Exclude<SweeteningSubstance, 'aspartame'>>): void;
+ *
+ * const artificiallySweetenedDessert = 'ice-cream' as string & Sweetener<'aspartame'>;
+ * eat(artificiallySweetenedDessert); // ERROR
+ * ```
+ */
+export type NominalType<TKey extends string, TMarker extends string> = {
+    readonly [K in `__${TKey}:@solana/kit`]: TMarker;
+};