@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 +20 -0
- package/README.md +85 -0
- package/dist/types/index.d.ts +112 -0
- package/dist/types/index.d.ts.map +1 -0
- package/package.json +43 -3
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": "
|
|
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
|
+
}
|