@solana/nominal-types 0.0.0 → 2.1.1-canary-20250512222749

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2025 Anza Technology, Inc
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1 +1,86 @@
1
+ [![npm][npm-image]][npm-url]
2
+ [![npm-downloads][npm-downloads-image]][npm-url]
3
+ <br />
4
+ [![code-style-prettier][code-style-prettier-image]][code-style-prettier-url]
5
+
6
+ [code-style-prettier-image]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square
7
+ [code-style-prettier-url]: https://github.com/prettier/prettier
8
+ [npm-downloads-image]: https://img.shields.io/npm/dm/@solana/nominal-types?style=flat
9
+ [npm-image]: https://img.shields.io/npm/v/@solana/nominal-types?style=flat
10
+ [npm-url]: https://www.npmjs.com/package/@solana/nominal-types
11
+
1
12
  # @solana/nominal-types
13
+
14
+ This package contains type utilities for creating nominal types in TypeScript.
15
+
16
+ ## Brands make otherwise equal values distinct at the type level
17
+
18
+ Use the `Brand` utility 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.
19
+
20
+ 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).
21
+
22
+ ```ts
23
+ const unverifiedName = 'Alice';
24
+ const verifiedName = unverifiedName as Brand<'Alice', 'VerifiedName'>;
25
+
26
+ 'Alice' satisfies Brand<string, 'VerifiedName'>; // ERROR
27
+ 'Alice' satisfies Brand<'Alice', 'VerifiedName'>; // ERROR
28
+ unverifiedName satisfies Brand<string, 'VerifiedName'>; // ERROR
29
+ verifiedName satisfies Brand<'Bob', 'VerifiedName'>; // ERROR
30
+ verifiedName satisfies Brand<'Alice', 'VerifiedName'>; // OK
31
+ verifiedName satisfies Brand<string, 'VerifiedName'>; // OK
32
+ ```
33
+
34
+ ## Values can be tagged as compressed data
35
+
36
+ Use the `CompressedData` utility to produce a new type that satisfies the original type, but adds extra type information that marks the type as containing compressed data.
37
+
38
+ ```ts
39
+ const untaggedData = new Uint8Array([/ ... *\/]);
40
+ const compressedData = untaggedData as CompressedData<typeof untaggedData, 'zstd'>;
41
+
42
+ compressedData satisfies CompressedData<Uint8Array, 'zstd'>; // OK
43
+ untaggedData satisfies CompressedData<Uint8Array, 'zstd'>; // ERROR
44
+ ```
45
+
46
+ ## Strings can be tagged as being encoded using a particular scheme
47
+
48
+ ```ts
49
+ const untaggedString = 'dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92';
50
+ const encodedString = untaggedString as EncodedString<typeof untaggedString, 'base58'>;
51
+
52
+ encodedString satisfies EncodedString<'dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92', 'base58'>; // OK
53
+ encodedString satisfies EncodedString<string, 'base58'>; // OK
54
+ encodedString satisfies EncodedString<string, 'base64'>; // ERROR
55
+ untaggedString satisfies EncodedString<string, 'base58'>; // ERROR
56
+ ```
57
+
58
+ ## Brands, compression, and encodings can be combined
59
+
60
+ ```ts
61
+ const encodedCompressedString = 'abc' as Brand<
62
+ EncodedString<CompressedData<'abc', 'zstd'>, 'base64'>,
63
+ 'Base64ZstdCompressedData'
64
+ >;
65
+
66
+ encodedCompressedString satisfies Brand<'abc', 'Base64ZstdCompressedData'>; // OK
67
+ encodedCompressedString satisfies Brand<string, 'Base64ZstdCompressedData'>; // OK
68
+ encodedCompressedString satisfies CompressedData<'abc', 'zstd'>; // OK
69
+ encodedCompressedString satisfies CompressedData<string, 'zstd'>; // OK
70
+ encodedCompressedString satisfies EncodedString<'abc', 'base64'>; // OK
71
+ encodedCompressedString satisfies EncodedString<string, 'base64'>; // OK
72
+ encodedCompressedString satisfies EncodedString<string, 'base58'>; // ERROR
73
+ ```
74
+
75
+ ## Custom nominal types
76
+
77
+ ```ts
78
+ type SweeteningSubstance = 'aspartame' | 'cane-sugar' | 'stevia';
79
+ type Sweetener<T extends SweeteningSubstance> = NominalType<'sweetener', T>;
80
+
81
+ // This function accepts sweetened foods, except those with aspartame.
82
+ declare function eat(food: string & Sweetener<Exclude<SweeteningSubstance, 'aspartame'>>): void;
83
+
84
+ const artificiallySweetenedDessert = 'ice-cream' as string & Sweetener<'aspartame'>;
85
+ eat(artificiallySweetenedDessert); // ERROR
86
+ ```
@@ -0,0 +1,112 @@
1
+ /**
2
+ * This package contains type utilities for creating nominal types in TypeScript.
3
+ *
4
+ * @example Brands, compression, and encodings can be combined
5
+ * ```ts
6
+ * const encodedCompressedString = 'abc' as Brand<
7
+ * EncodedString<CompressedData<'abc', 'zstd'>, 'base64'>,
8
+ * 'Base64ZstdCompressedData'
9
+ * >;
10
+ *
11
+ * encodedCompressedString satisfies Brand<'abc', 'Base64ZstdCompressedData'>; // OK
12
+ * encodedCompressedString satisfies Brand<string, 'Base64ZstdCompressedData'>; // OK
13
+ * encodedCompressedString satisfies CompressedData<'abc', 'zstd'>; // OK
14
+ * encodedCompressedString satisfies CompressedData<string, 'zstd'>; // OK
15
+ * encodedCompressedString satisfies EncodedString<'abc', 'base64'>; // OK
16
+ * encodedCompressedString satisfies EncodedString<string, 'base64'>; // OK
17
+ * encodedCompressedString satisfies EncodedString<string, 'base58'>; // ERROR
18
+ * ```
19
+ *
20
+ * @packageDocumentation
21
+ */
22
+ type CompressionFormat = 'zstd';
23
+ type StringEncoding = 'base58' | 'base64';
24
+ /**
25
+ * Use this to produce a new type that satisfies the original type, but not the other way around.
26
+ * That is to say, the branded type is acceptable wherever the original type is specified, but
27
+ * wherever the branded type is specified, the original type will be insufficient.
28
+ *
29
+ * You can use this to create specialized instances of strings, numbers, objects, and more which
30
+ * you would like to assert are special in some way (eg. numbers that are non-negative, strings
31
+ * which represent the names of foods, objects that have passed validation).
32
+ *
33
+ * @typeParam T - The base type to brand
34
+ * @typeParam TBrandName - A string that identifies a particular brand. Branded types with identical
35
+ * names will satisfy each other so long as their base types satisfy each other. Branded types with
36
+ * different names will never satisfy each other.
37
+ *
38
+ * @example
39
+ * ```ts
40
+ * const unverifiedName = 'Alice';
41
+ * const verifiedName = unverifiedName as Brand<'Alice', 'VerifiedName'>;
42
+ *
43
+ * 'Alice' satisfies Brand<string, 'VerifiedName'>; // ERROR
44
+ * 'Alice' satisfies Brand<'Alice', 'VerifiedName'>; // ERROR
45
+ * unverifiedName satisfies Brand<string, 'VerifiedName'>; // ERROR
46
+ * verifiedName satisfies Brand<'Bob', 'VerifiedName'>; // ERROR
47
+ * verifiedName satisfies Brand<'Alice', 'VerifiedName'>; // OK
48
+ * verifiedName satisfies Brand<string, 'VerifiedName'>; // OK
49
+ * ```
50
+ */
51
+ export type Brand<T, TBrandName extends string> = NominalType<'brand', TBrandName> & T;
52
+ /**
53
+ * Use this to produce a new type that satisfies the original type, but adds extra type information
54
+ * that marks the type as containing compressed data.
55
+ *
56
+ * @typeParam T - The base type to mark as representing compressed data
57
+ * @typeParam TFormat - The compression format of the underlying data
58
+ *
59
+ * @example
60
+ * ```ts
61
+ * const untaggedData = new Uint8Array([/* ... *\/]);
62
+ * const compressedData = untaggedData as CompressedData<typeof untaggedData, 'zstd'>;
63
+ *
64
+ * compressedData satisfies CompressedData<Uint8Array, 'zstd'>; // OK
65
+ * untaggedData satisfies CompressedData<Uint8Array, 'zstd'>; // ERROR
66
+ * ```
67
+ */
68
+ export type CompressedData<T, TFormat extends CompressionFormat> = NominalType<'compressionFormat', TFormat> & T;
69
+ /**
70
+ * Use this to produce a new type that satisfies the original string type, but adds extra type
71
+ * information that marks the string as being encoded in a particular format.
72
+ *
73
+ * @typeParam T - The underlying string type
74
+ * @typeParam TEncoding - The encoding format of the string
75
+ *
76
+ * @example
77
+ * ```ts
78
+ * const untaggedString = 'dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92';
79
+ * const encodedString = untaggedString as EncodedString<typeof untaggedString, 'base58'>;
80
+ *
81
+ * encodedString satisfies EncodedString<'dv1ZAGvdsz5hHLwWXsVnM94hWf1pjbKVau1QVkaMJ92', 'base58'>; // OK
82
+ * encodedString satisfies EncodedString<string, 'base58'>; // OK
83
+ * encodedString satisfies EncodedString<string, 'base64'>; // ERROR
84
+ * untaggedString satisfies EncodedString<string, 'base58'>; // ERROR
85
+ * ```
86
+ */
87
+ export type EncodedString<T extends string, TEncoding extends StringEncoding> = NominalType<'stringEncoding', TEncoding> & T;
88
+ /**
89
+ * Use this to produce a nominal type.
90
+ *
91
+ * This can be intersected with other base types to produce custom branded types.
92
+ *
93
+ * @typeParam TKey - The name of the nominal type. This distinguishes one nominal type from another.
94
+ * @typeParam TMarker - The type of the value the nominal type can take.
95
+ *
96
+ * @example
97
+ * ```ts
98
+ * type SweeteningSubstance = 'aspartame' | 'cane-sugar' | 'stevia';
99
+ * type Sweetener<T extends SweeteningSubstance> = NominalType<'sweetener', T>;
100
+ *
101
+ * // This function accepts sweetened foods, except those with aspartame.
102
+ * declare function eat(food: string & Sweetener<Exclude<SweeteningSubstance, 'aspartame'>>): void;
103
+ *
104
+ * const artificiallySweetenedDessert = 'ice-cream' as string & Sweetener<'aspartame'>;
105
+ * eat(artificiallySweetenedDessert); // ERROR
106
+ * ```
107
+ */
108
+ export type NominalType<TKey extends string, TMarker extends string> = {
109
+ readonly [K in `__${TKey}:@solana/kit`]: TMarker;
110
+ };
111
+ export {};
112
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,KAAK,iBAAiB,GAAG,MAAM,CAAC;AAChC,KAAK,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,UAAU,SAAS,MAAM,IAAI,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;AAEvF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,EAAE,OAAO,SAAS,iBAAiB,IAAI,WAAW,CAAC,mBAAmB,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;AAEjH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,SAAS,cAAc,IAAI,WAAW,CACvF,gBAAgB,EAChB,SAAS,CACZ,GACG,CAAC,CAAC;AAEN;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,OAAO,SAAS,MAAM,IAAI;IACnE,QAAQ,EAAE,CAAC,IAAI,KAAK,IAAI,cAAc,GAAG,OAAO;CACnD,CAAC"}
package/package.json CHANGED
@@ -1,5 +1,45 @@
1
1
  {
2
2
  "name": "@solana/nominal-types",
3
- "version": "0.0.0",
4
- "description": ""
5
- }
3
+ "version": "2.1.1-canary-20250512222749",
4
+ "description": "Type utilties for creating nominal/branded types in TypeScript",
5
+ "types": "./dist/types/index.d.ts",
6
+ "type": "commonjs",
7
+ "files": [
8
+ "./dist/"
9
+ ],
10
+ "sideEffects": false,
11
+ "keywords": [
12
+ "blockchain",
13
+ "solana",
14
+ "web3"
15
+ ],
16
+ "author": "Solana Labs Maintainers <maintainers@solanalabs.com>",
17
+ "license": "MIT",
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "https://github.com/anza-xyz/kit"
21
+ },
22
+ "bugs": {
23
+ "url": "https://github.com/anza-xyz/kit/issues"
24
+ },
25
+ "browserslist": [
26
+ "supports bigint and not dead",
27
+ "maintained node versions"
28
+ ],
29
+ "peerDependencies": {
30
+ "typescript": ">=5.3.3"
31
+ },
32
+ "engines": {
33
+ "node": ">=20.18.0"
34
+ },
35
+ "scripts": {
36
+ "compile:docs": "typedoc",
37
+ "compile:typedefs": "tsc -p ./tsconfig.declarations.json",
38
+ "publish-impl": "npm view $npm_package_name@$npm_package_version > /dev/null 2>&1 || (pnpm publish --tag ${PUBLISH_TAG:-canary} --access public --no-git-checks && (([ \"$PUBLISH_TAG\" != \"canary\" ] && pnpm dist-tag add $npm_package_name@$npm_package_version latest) || true))",
39
+ "publish-packages": "pnpm prepublishOnly && pnpm publish-impl",
40
+ "style:fix": "pnpm eslint --fix src && pnpm prettier --log-level warn --ignore-unknown --write ./*",
41
+ "test:lint": "TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@solana/test-config/jest-lint.config.ts --rootDir . --silent",
42
+ "test:prettier": "TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@solana/test-config/jest-prettier.config.ts --rootDir . --silent",
43
+ "test:typecheck": "tsc --noEmit"
44
+ }
45
+ }