bufferbase 2.0.0 → 3.0.0

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.
Files changed (115) hide show
  1. package/README.md +151 -63
  2. package/dist/cjs/bases.d.ts +152 -45
  3. package/dist/cjs/bases.d.ts.map +1 -1
  4. package/dist/cjs/bases.js +90 -77
  5. package/dist/cjs/bases.js.map +1 -1
  6. package/dist/cjs/bufferbase.d.ts +21 -27
  7. package/dist/cjs/bufferbase.d.ts.map +1 -1
  8. package/dist/cjs/bufferbase.js +21 -31
  9. package/dist/cjs/bufferbase.js.map +1 -1
  10. package/dist/cjs/codec-base.d.ts +56 -0
  11. package/dist/cjs/codec-base.d.ts.map +1 -0
  12. package/dist/cjs/codec-base.js +132 -0
  13. package/dist/cjs/codec-base.js.map +1 -0
  14. package/dist/cjs/codec-block.d.ts +47 -0
  15. package/dist/cjs/codec-block.d.ts.map +1 -0
  16. package/dist/cjs/codec-block.js +213 -0
  17. package/dist/cjs/codec-block.js.map +1 -0
  18. package/dist/cjs/codec-block85.d.ts +56 -0
  19. package/dist/cjs/codec-block85.d.ts.map +1 -0
  20. package/dist/cjs/codec-block85.js +271 -0
  21. package/dist/cjs/codec-block85.js.map +1 -0
  22. package/dist/cjs/codec-radix.d.ts +46 -0
  23. package/dist/cjs/codec-radix.d.ts.map +1 -0
  24. package/dist/cjs/codec-radix.js +181 -0
  25. package/dist/cjs/codec-radix.js.map +1 -0
  26. package/dist/cjs/codec.d.ts +25 -111
  27. package/dist/cjs/codec.d.ts.map +1 -1
  28. package/dist/cjs/codec.js +50 -228
  29. package/dist/cjs/codec.js.map +1 -1
  30. package/dist/cjs/codecs.d.ts +8 -59
  31. package/dist/cjs/codecs.d.ts.map +1 -1
  32. package/dist/cjs/codecs.js +6 -79
  33. package/dist/cjs/codecs.js.map +1 -1
  34. package/dist/cjs/errors.d.ts +65 -48
  35. package/dist/cjs/errors.d.ts.map +1 -1
  36. package/dist/cjs/errors.js +89 -51
  37. package/dist/cjs/errors.js.map +1 -1
  38. package/dist/cjs/example.js +44 -21
  39. package/dist/cjs/example.js.map +1 -1
  40. package/dist/cjs/functions.d.ts +27 -31
  41. package/dist/cjs/functions.d.ts.map +1 -1
  42. package/dist/cjs/functions.js +25 -47
  43. package/dist/cjs/functions.js.map +1 -1
  44. package/dist/cjs/index.d.ts +7 -5
  45. package/dist/cjs/index.d.ts.map +1 -1
  46. package/dist/cjs/index.js +17 -7
  47. package/dist/cjs/index.js.map +1 -1
  48. package/dist/cjs/package.json +13 -7
  49. package/dist/cjs/types.d.ts +108 -71
  50. package/dist/cjs/types.d.ts.map +1 -1
  51. package/dist/esm/bases.d.ts +152 -45
  52. package/dist/esm/bases.d.ts.map +1 -1
  53. package/dist/esm/bases.js +88 -75
  54. package/dist/esm/bases.js.map +1 -1
  55. package/dist/esm/bufferbase.d.ts +21 -27
  56. package/dist/esm/bufferbase.d.ts.map +1 -1
  57. package/dist/esm/bufferbase.js +18 -30
  58. package/dist/esm/bufferbase.js.map +1 -1
  59. package/dist/esm/codec-base.d.ts +56 -0
  60. package/dist/esm/codec-base.d.ts.map +1 -0
  61. package/dist/esm/codec-base.js +127 -0
  62. package/dist/esm/codec-base.js.map +1 -0
  63. package/dist/esm/codec-block.d.ts +47 -0
  64. package/dist/esm/codec-block.d.ts.map +1 -0
  65. package/dist/esm/codec-block.js +209 -0
  66. package/dist/esm/codec-block.js.map +1 -0
  67. package/dist/esm/codec-block85.d.ts +56 -0
  68. package/dist/esm/codec-block85.d.ts.map +1 -0
  69. package/dist/esm/codec-block85.js +267 -0
  70. package/dist/esm/codec-block85.js.map +1 -0
  71. package/dist/esm/codec-radix.d.ts +46 -0
  72. package/dist/esm/codec-radix.d.ts.map +1 -0
  73. package/dist/esm/codec-radix.js +177 -0
  74. package/dist/esm/codec-radix.js.map +1 -0
  75. package/dist/esm/codec.d.ts +25 -111
  76. package/dist/esm/codec.d.ts.map +1 -1
  77. package/dist/esm/codec.js +44 -226
  78. package/dist/esm/codec.js.map +1 -1
  79. package/dist/esm/codecs.d.ts +8 -59
  80. package/dist/esm/codecs.d.ts.map +1 -1
  81. package/dist/esm/codecs.js +7 -80
  82. package/dist/esm/codecs.js.map +1 -1
  83. package/dist/esm/errors.d.ts +65 -48
  84. package/dist/esm/errors.d.ts.map +1 -1
  85. package/dist/esm/errors.js +83 -50
  86. package/dist/esm/errors.js.map +1 -1
  87. package/dist/esm/example.js +45 -22
  88. package/dist/esm/example.js.map +1 -1
  89. package/dist/esm/functions.d.ts +27 -31
  90. package/dist/esm/functions.d.ts.map +1 -1
  91. package/dist/esm/functions.js +26 -48
  92. package/dist/esm/functions.js.map +1 -1
  93. package/dist/esm/index.d.ts +7 -5
  94. package/dist/esm/index.d.ts.map +1 -1
  95. package/dist/esm/index.js +6 -6
  96. package/dist/esm/index.js.map +1 -1
  97. package/dist/esm/package.json +13 -7
  98. package/dist/esm/types.d.ts +108 -71
  99. package/dist/esm/types.d.ts.map +1 -1
  100. package/package.json +13 -7
  101. package/src/algorithms.test.ts +442 -0
  102. package/src/bases.ts +98 -76
  103. package/src/bufferbase.ts +26 -36
  104. package/src/codec-base.ts +181 -0
  105. package/src/codec-block.ts +258 -0
  106. package/src/codec-block85.ts +315 -0
  107. package/src/codec-radix.ts +206 -0
  108. package/src/codec.test.ts +17 -9
  109. package/src/codec.ts +48 -247
  110. package/src/codecs.ts +11 -105
  111. package/src/errors.ts +90 -50
  112. package/src/example.ts +47 -22
  113. package/src/functions.ts +34 -54
  114. package/src/index.ts +27 -7
  115. package/src/types.ts +113 -86
package/README.md CHANGED
@@ -1,6 +1,7 @@
1
1
  # bufferbase
2
2
 
3
- Buffer-to-BaseN encoding and decoding for Node.js.
3
+ Buffer-to-BaseN encoding for Node.js and the browser, across three algorithms:
4
+ RFC 4648 bit-block encodings, Ascii85/Z85, and Base58-style radix conversion.
4
5
 
5
6
  ## Installation
6
7
 
@@ -8,106 +9,193 @@ Buffer-to-BaseN encoding and decoding for Node.js.
8
9
  npm install bufferbase
9
10
  ```
10
11
 
12
+ ## The three algorithms
13
+
14
+ An alphabet does not describe an encoding on its own. The same 64 characters
15
+ can be read as a radix conversion or as a bit-block encoding, and the two
16
+ produce different strings for the same bytes. Every codec here therefore names
17
+ its algorithm.
18
+
19
+ | Algorithm | How it works | Alphabet | Used by |
20
+ |---|---|---|---|
21
+ | `block` | Regroups the bit stream into `log2(n)`-bit chunks, per RFC 4648 | 2, 4, 8, 16, 32, or 64 characters | Base16, Base32, Base64 |
22
+ | `block85` | Converts each 4-byte block to 5 characters | exactly 85 characters | Ascii85, Z85 |
23
+ | `radix` | Reads the buffer as one integer and rewrites it in base `n` | any length | Base58, Base36, Crockford |
24
+
25
+ ```typescript
26
+ import { encode } from 'bufferbase';
27
+
28
+ encode(Buffer.from('fo'), 'base64'); // 'Zm8=' — RFC 4648
29
+ encode(Buffer.from('fo'), 'radix64'); // 'GZv' — radix conversion
30
+ ```
31
+
32
+ Only `radix` accepts an alphabet of any length, and only `radix` preserves
33
+ leading zero bytes as leading characters. Only `block` and `block85` have an
34
+ output length that is a fixed function of the input length.
35
+
36
+ ## Supported encodings
37
+
38
+ | Name | Algorithm | Characters | Notes |
39
+ |---|---|---|---|
40
+ | `base16`, `hex` | `block` | 0-9A-F | RFC 4648 Table 5, unpadded |
41
+ | `base32` | `block` | A-Z2-7 | RFC 4648 Table 3 |
42
+ | `base32hex` | `block` | 0-9A-V | RFC 4648 Table 4 |
43
+ | `base64` | `block` | A-Za-z0-9+/ | RFC 4648 Table 1 |
44
+ | `base64url` | `block` | A-Za-z0-9-_ | RFC 4648 Table 2, unpadded |
45
+ | `base64xml` | `block` | A-Za-z0-9._ | unpadded |
46
+ | `base64xmlname` | `block` | A-Za-z0-9_: | unpadded |
47
+ | `ascii85` | `block85` | `!` to `u` | zero-block shortcut on |
48
+ | `z85` | `block85` | ZeroMQ RFC 32 | whole 4-byte blocks only |
49
+ | `base58` | `radix` | Bitcoin alphabet | |
50
+ | `base32crockford` | `radix` | 0-9A-HJKMNP-TV-Z | |
51
+ | `base32crockfordcheck` | `radix` | as above, plus `*~$=U` | carries a check symbol |
52
+ | `base36` | `radix` | 0-9A-Z | case-insensitive |
53
+ | `base52` | `radix` | A-Za-z | |
54
+ | `decimal` | `radix` | 0-9 | |
55
+ | `radix16`, `radix32`, `radix64`, `radix64url` | `radix` | the RFC alphabets | radix conversion, not RFC 4648 |
56
+
57
+ Base16, Base32, Base32hex, Base36 and both Crockford codecs decode in either
58
+ case.
59
+
11
60
  ## Usage
12
61
 
13
- ### Simple Function API
62
+ ### Functions
14
63
 
15
64
  ```typescript
16
65
  import { encode, decode, convert, validate } from 'bufferbase';
17
66
 
18
- // Encode buffer to base58
19
- const encoded = encode(Buffer.from('Hello'), 'base58');
67
+ encode(Buffer.from('Hello'), 'base58'); // '9Ajdvzr'
68
+ decode('9Ajdvzr', 'base58'); // Buffer('Hello')
69
+ decode('9Ajdvzr', 'base58', { size: 32 }); // padded to 32 bytes
70
+ convert('9Ajdvzr', 'base58', 'base64url'); // through the bytes
71
+ validate('Zm8=', 'base64'); // true
72
+ ```
20
73
 
21
- // Decode base58 string to buffer
22
- const decoded = decode(encoded, 'base58');
74
+ `validate(input, base)` returns `true` exactly when `decode(input, base)`
75
+ succeeds, so the two never disagree.
23
76
 
24
- // Decode with fixed size (pads with leading zeros)
25
- const fixed = decode(encoded, 'base58', { size: 32 });
77
+ ### Codecs
26
78
 
27
- // Convert between bases
28
- const base64 = convert(encoded, 'base58', 'base64url');
79
+ ```typescript
80
+ import { Codecs } from 'bufferbase';
29
81
 
30
- // Validate string
31
- validate('9Ajdvz', 'base58'); // true
32
- validate('0Ajdvz', 'base58'); // false ('0' not in base58)
82
+ Codecs.base64.encode(Buffer.from('fo')); // 'Zm8='
83
+ Codecs.base58.convertTo(Codecs.base64url, '9Ajdvzr');
33
84
  ```
34
85
 
35
- ### Pre-defined Codecs
86
+ ### Custom codecs
87
+
88
+ Pass a spec anywhere a base name is accepted.
36
89
 
37
90
  ```typescript
38
- import { Codecs } from 'bufferbase';
91
+ import { createCodec, encode } from 'bufferbase';
92
+
93
+ encode(Uint8Array.of(5), { alphabet: '01', algorithm: 'radix' }); // '101'
94
+
95
+ const lowerHex = createCodec({ alphabet: '0123456789abcdef', algorithm: 'block', pad: false });
96
+ lowerHex.encode(Uint8Array.of(0, 1)); // '0001'
97
+
98
+ createCodec('01'); // a bare string means a radix codec over that alphabet
99
+ ```
39
100
 
40
- const encoded = Codecs.base58.encode(Buffer.from('Hello'));
41
- const decoded = Codecs.base58.decode(encoded);
101
+ ### Crockford's Base32
42
102
 
43
- // Convert between codecs
44
- const base64 = Codecs.base58.convertTo(Codecs.base64url, encoded);
103
+ Crockford's specification describes a notation for numbers rather than for byte
104
+ streams, so a radix conversion is the right reading of it. Decoding accepts
105
+ either case, reads `I` and `L` as `1` and `O` as `0`, and ignores the hyphens
106
+ that may be inserted for readability. Encoding emits only the alphabet.
45
107
 
46
- // Validate
47
- Codecs.base58.validate('9Ajdvz'); // true
108
+ ```typescript
109
+ decode('91jprv3f', 'base32crockford'); // Buffer('Hello')
110
+ decode('91JP-RV3F', 'base32crockford'); // the same
111
+ decode('9IJPRV3F', 'base32crockford'); // the same, reading I as 1
48
112
  ```
49
113
 
50
- ### Custom Character Set
114
+ `base32crockfordcheck` appends the check symbol, the value modulo 37 written
115
+ with the alphabet extended by `*~$=U`. Decoding verifies it, so a mistyped
116
+ character is caught rather than decoded into different bytes.
51
117
 
52
118
  ```typescript
53
- import { createCodec } from 'bufferbase';
119
+ encode(Buffer.from('Hello'), 'base32crockfordcheck'); // '91JPRV3FG'
120
+ validate('91JPRV3XG', 'base32crockfordcheck'); // false
121
+ ```
122
+
123
+ ### Ascii85 variants
124
+
125
+ Several incompatible encodings share the Ascii85 algorithm and alphabet,
126
+ differing only in the shortcuts and framing they add. They are options rather
127
+ than separate codecs. The `ascii85` default is `zeroShortcut` alone, which
128
+ matches Python's `base64.a85encode`.
54
129
 
55
- const binary = createCodec('01');
56
- binary.encode(Buffer.from([5])); // '101'
57
- binary.decode('101'); // Buffer([5])
130
+ ```typescript
131
+ import { createCodec, Chars } from 'bufferbase';
132
+
133
+ const btoa = createCodec({
134
+ alphabet: Chars.Ascii85, algorithm: 'block85',
135
+ zeroShortcut: true, spaceShortcut: true, // ' ' -> 'y'
136
+ });
137
+
138
+ const adobe = createCodec({
139
+ alphabet: Chars.Ascii85, algorithm: 'block85',
140
+ zeroShortcut: true, delimiters: true, // '<~ ... ~>'
141
+ });
58
142
  ```
59
143
 
60
- ## Supported Encodings
61
-
62
- | Name | Characters |
63
- |------|------------|
64
- | `decimal` | 0-9 |
65
- | `base16` / `hex` | 0-9A-F |
66
- | `base32` | A-Z2-7 |
67
- | `base32crockford` | 0-9A-HJKMNP-TV-Z |
68
- | `base36` | 0-9A-Z |
69
- | `base52` | A-Za-z |
70
- | `base58` | Bitcoin alphabet (no 0OIl) |
71
- | `base64` | A-Za-z0-9+/ |
72
- | `base64url` | A-Za-z0-9-_ |
73
- | `base64xml` | A-Za-z0-9._ |
74
- | `base64xmlname` | A-Za-z0-9_: |
75
- | `ascii85` | ASCII85 |
76
- | `base85` | Base85 |
77
- | `z85` | ZeroMQ Z85 |
144
+ ## Canonical encodings
78
145
 
79
- ## API
146
+ A trailing partial block leaves spare bits in the final character. RFC 4648
147
+ §3.5 requires them to be zero; input that sets them decodes to the same bytes
148
+ as the canonical form, so accepting it makes decoding non-injective.
80
149
 
81
- ### Functions
150
+ ```typescript
151
+ decode('Zm8=', 'base64'); // Buffer('fo')
152
+ decode('Zm9=', 'base64'); // throws NonCanonicalError — also 'fo'
153
+ ```
154
+
155
+ This is rejected by default. Pass `strict: false` to read data from a lenient
156
+ encoder.
82
157
 
83
- - `encode(buffer, base)` - Encode buffer to string
84
- - `decode(encoded, base, options?)` - Decode string to buffer
85
- - `convert(input, from, to)` - Convert between bases
86
- - `validate(input, base)` - Check if string is valid for base
87
- - `createCodec(chars)` - Create codec with custom character set
158
+ ```typescript
159
+ createCodec({ alphabet: Chars.Base64, algorithm: 'block', strict: false });
160
+ ```
88
161
 
89
- ### Codecs Object
162
+ The same check rejects lengths that cannot be a whole number of bytes
163
+ (`'Zm9vd'`), misplaced or excess padding, and Ascii85 groups above 2^32.
164
+
165
+ ## API
90
166
 
91
167
  ```typescript
92
- Codecs.base58.encode(buffer)
93
- Codecs.base58.decode(encoded, options?)
94
- Codecs.base58.validate(input)
95
- Codecs.base58.convertTo(targetCodec, input)
168
+ encode(buffer, base) // string
169
+ decode(encoded, base, options?) // Buffer
170
+ convert(input, from, to) // string
171
+ validate(input, base) // boolean
172
+ createCodec(spec | alphabet) // ICodec
96
173
  ```
97
174
 
98
- ### Options
175
+ `base` is a name from the table above or a `CodecSpec`. Every spec accepts
176
+ `strict`, `caseInsensitive`, `aliases` and `ignore`:
99
177
 
100
178
  ```typescript
101
- interface DecodeOptions {
102
- size?: number; // Expected buffer size (pads with zeros if smaller)
103
- }
179
+ type CodecSpec =
180
+ | { alphabet: string; algorithm: 'radix'; checkSymbols?: string }
181
+ | { alphabet: string; algorithm: 'block'; pad?: string | false }
182
+ | { alphabet: string; algorithm: 'block85';
183
+ zeroShortcut?: boolean; spaceShortcut?: boolean;
184
+ delimiters?: boolean; requireFullBlocks?: boolean };
104
185
  ```
105
186
 
106
187
  ### Errors
107
188
 
108
- - `InvalidCharacterError` - Invalid character in decode input
109
- - `BufferSizeError` - Decoded buffer exceeds specified size
110
- - `UnknownBaseError` - Unknown base name
189
+ | Error | Thrown when |
190
+ |---|---|
191
+ | `InvalidCharacterError` | a character is not in the alphabet |
192
+ | `InvalidLengthError` | the length cannot encode a whole number of bytes |
193
+ | `NonCanonicalError` | spare bits are set and the codec is strict |
194
+ | `ValueRangeError` | a block85 group is 2^32 or above |
195
+ | `CheckSymbolError` | a check symbol does not match the value it follows |
196
+ | `BufferSizeError` | the result does not have the requested `size` |
197
+ | `UnknownBaseError` | the base name is not known |
198
+ | `InvalidCodecError` | the spec cannot be realised |
111
199
 
112
200
  ## License
113
201
 
@@ -1,25 +1,19 @@
1
- import type { BaseName } from './types.js';
1
+ import type { CodecSpec } from './types.js';
2
2
  /**
3
- * Character sets for common base encodings.
3
+ * Character sets, ordered by value.
4
4
  *
5
- * Use these with `createCodec()` or the deprecated `BufferEncoder` class
6
- * when you need direct access to character sets.
7
- *
8
- * @example
9
- * ```typescript
10
- * import { Chars, createCodec } from 'bufferbase';
11
- *
12
- * const codec = createCodec(Chars.Base58);
13
- * const encoded = codec.encode(Buffer.from('Hello'));
14
- * ```
5
+ * A character set does not by itself describe an encoding — see `Bases` for
6
+ * the alphabet/algorithm pairs that do.
15
7
  */
16
8
  export declare const Chars: {
17
9
  /** Base 10: 0-9 */
18
10
  readonly Decimal: "0123456789";
19
- /** Hexadecimal: 0-9A-F */
11
+ /** RFC 4648 Table 5 — Base16: 0-9A-F */
20
12
  readonly Base16: "0123456789ABCDEF";
21
- /** RFC 4648 Base32: A-Z2-7 */
13
+ /** RFC 4648 Table 3 — Base32: A-Z2-7 */
22
14
  readonly Base32: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
15
+ /** RFC 4648 Table 4 — Base32 with extended hex alphabet: 0-9A-V */
16
+ readonly Base32Hex: "0123456789ABCDEFGHIJKLMNOPQRSTUV";
23
17
  /** Crockford's Base32: 0-9A-HJKMNP-TV-Z (no I, L, O, U) */
24
18
  readonly Base32Crockford: "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
25
19
  /** Alphanumeric: 0-9A-Z */
@@ -28,55 +22,168 @@ export declare const Chars: {
28
22
  readonly Base52: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
29
23
  /** Bitcoin alphabet: 1-9A-HJ-NP-Za-km-z (no 0, O, I, l) */
30
24
  readonly Base58: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
31
- /** Standard Base64: A-Za-z0-9+/ */
25
+ /** RFC 4648 Table 1 — Base64: A-Za-z0-9+/ */
32
26
  readonly Base64: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
33
- /** URL-safe Base64: A-Za-z0-9-_ */
27
+ /** RFC 4648 Table 2 — URL-safe Base64: A-Za-z0-9-_ */
34
28
  readonly Base64Url: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
35
29
  /** XML token Base64: A-Za-z0-9._ */
36
30
  readonly Base64Xml: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._";
37
31
  /** XML name Base64: A-Za-z0-9_: */
38
32
  readonly Base64XmlName: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_:";
39
- /** ASCII85 encoding */
40
- readonly Ascii85: "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`abcdefghijklmnopqrstu";
41
- /** Base85 encoding */
42
- readonly Base85: "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!#$%&()*+-;<=>?@^_`{|}~";
43
- /** ZeroMQ Z85 encoding */
33
+ /** Ascii85: the 85 printable characters from `!` (0x21) to `u` (0x75) */
34
+ readonly Ascii85: "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstu";
35
+ /** ZeroMQ Z85 (RFC 32): avoids the quote and backslash characters */
44
36
  readonly Z85: "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#";
37
+ /** The five symbols Crockford's Base32 adds for its check symbol, giving a modulus of 37 */
38
+ readonly CrockfordCheck: "*~$=U";
45
39
  };
46
40
  /**
47
- * Resolves a base name or character set string to a character set.
48
- *
49
- * This function is used internally by the function API to convert
50
- * base names (like `'base58'`) to their character sets.
41
+ * The encodings this package knows by name.
51
42
  *
52
- * @param base - Base name (e.g., `'base58'`) or custom character set string
53
- * @returns The character set string
54
- * @throws {UnknownBaseError} If base name is not recognized and string length <= 15
43
+ * Each entry pairs an alphabet with the algorithm that reads it, because the
44
+ * alphabet alone is ambiguous: `base64` and `radix64` share Table 1 but
45
+ * produce different strings for the same bytes.
55
46
  *
56
47
  * @example
57
48
  * ```typescript
58
- * import { resolveChars } from 'bufferbase';
49
+ * import { encode, Bases } from 'bufferbase';
59
50
  *
60
- * resolveChars('base58'); // Returns Bitcoin alphabet
61
- * resolveChars('0123456789ABCDEF'); // Returns the string as-is (custom charset)
62
- * resolveChars('invalid'); // Throws UnknownBaseError
51
+ * encode(Buffer.from('fo'), 'base64'); // 'Zm8=' — RFC 4648
52
+ * encode(Buffer.from('fo'), 'radix64'); // 'GZv' — radix conversion
63
53
  * ```
64
54
  */
65
- export declare function resolveChars(base: BaseName | string): string;
55
+ export declare const Bases: {
56
+ readonly decimal: {
57
+ readonly alphabet: "0123456789";
58
+ readonly algorithm: "radix";
59
+ };
60
+ readonly base36: {
61
+ readonly alphabet: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
62
+ readonly algorithm: "radix";
63
+ readonly caseInsensitive: true;
64
+ };
65
+ readonly base52: {
66
+ readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
67
+ readonly algorithm: "radix";
68
+ };
69
+ readonly base58: {
70
+ readonly alphabet: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
71
+ readonly algorithm: "radix";
72
+ };
73
+ /**
74
+ * Crockford's Base32, which specifies a notation for numbers rather than for
75
+ * byte streams, so a radix conversion is the right reading of it.
76
+ *
77
+ * Decoding accepts either case, reads `I` and `L` as `1` and `O` as `0`, and
78
+ * ignores hyphens.
79
+ */
80
+ readonly base32crockford: {
81
+ readonly alphabet: "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
82
+ readonly algorithm: "radix";
83
+ readonly caseInsensitive: true;
84
+ readonly aliases: {
85
+ readonly I: "1";
86
+ readonly L: "1";
87
+ readonly O: "0";
88
+ };
89
+ readonly ignore: "-";
90
+ };
91
+ /** Crockford's Base32 carrying its trailing check symbol. */
92
+ readonly base32crockfordcheck: {
93
+ readonly alphabet: "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
94
+ readonly algorithm: "radix";
95
+ readonly caseInsensitive: true;
96
+ readonly aliases: {
97
+ readonly I: "1";
98
+ readonly L: "1";
99
+ readonly O: "0";
100
+ };
101
+ readonly ignore: "-";
102
+ readonly checkSymbols: "*~$=U";
103
+ };
104
+ readonly base16: {
105
+ readonly alphabet: "0123456789ABCDEF";
106
+ readonly algorithm: "block";
107
+ readonly pad: false;
108
+ readonly caseInsensitive: true;
109
+ };
110
+ readonly hex: {
111
+ readonly alphabet: "0123456789ABCDEF";
112
+ readonly algorithm: "block";
113
+ readonly pad: false;
114
+ readonly caseInsensitive: true;
115
+ };
116
+ readonly base32: {
117
+ readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
118
+ readonly algorithm: "block";
119
+ readonly caseInsensitive: true;
120
+ };
121
+ readonly base32hex: {
122
+ readonly alphabet: "0123456789ABCDEFGHIJKLMNOPQRSTUV";
123
+ readonly algorithm: "block";
124
+ readonly caseInsensitive: true;
125
+ };
126
+ readonly base64: {
127
+ readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
128
+ readonly algorithm: "block";
129
+ };
130
+ /** Unpadded, as used by JWT and other URL-facing formats. */
131
+ readonly base64url: {
132
+ readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
133
+ readonly algorithm: "block";
134
+ readonly pad: false;
135
+ };
136
+ readonly base64xml: {
137
+ readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._";
138
+ readonly algorithm: "block";
139
+ readonly pad: false;
140
+ };
141
+ readonly base64xmlname: {
142
+ readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_:";
143
+ readonly algorithm: "block";
144
+ readonly pad: false;
145
+ };
146
+ /** Ascii85 with the zero-block shortcut, matching Python's `a85encode`. */
147
+ readonly ascii85: {
148
+ readonly alphabet: "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstu";
149
+ readonly algorithm: "block85";
150
+ readonly zeroShortcut: true;
151
+ };
152
+ /** ZeroMQ Z85, which has no padding and so encodes whole blocks only. */
153
+ readonly z85: {
154
+ readonly alphabet: "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#";
155
+ readonly algorithm: "block85";
156
+ readonly requireFullBlocks: true;
157
+ };
158
+ readonly radix16: {
159
+ readonly alphabet: "0123456789ABCDEF";
160
+ readonly algorithm: "radix";
161
+ };
162
+ readonly radix32: {
163
+ readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
164
+ readonly algorithm: "radix";
165
+ };
166
+ readonly radix64: {
167
+ readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
168
+ readonly algorithm: "radix";
169
+ };
170
+ readonly radix64url: {
171
+ readonly alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
172
+ readonly algorithm: "radix";
173
+ };
174
+ };
66
175
  /**
67
- * Checks if a string is a valid base name.
68
- *
69
- * @param value - The string to check
70
- * @returns `true` if the value is a valid `BaseName`, `false` otherwise
71
- *
72
- * @example
73
- * ```typescript
74
- * import { isBaseName } from 'bufferbase';
176
+ * The names accepted wherever a base is expected.
177
+ */
178
+ export type BaseName = keyof typeof Bases;
179
+ /**
180
+ * Resolves a base name to its codec spec, and passes a spec through unchanged.
75
181
  *
76
- * isBaseName('base58'); // true
77
- * isBaseName('BASE58'); // true (case-insensitive)
78
- * isBaseName('unknown'); // false
79
- * ```
182
+ * @throws {UnknownBaseError} If the name is not one of `Bases`
183
+ */
184
+ export declare function resolveSpec(base: BaseName | CodecSpec): CodecSpec;
185
+ /**
186
+ * Checks whether a string names one of the encodings in `Bases`.
80
187
  */
81
188
  export declare function isBaseName(value: string): value is BaseName;
82
189
  //# sourceMappingURL=bases.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"bases.d.ts","sourceRoot":"","sources":["../../src/bases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK;IAChB,mBAAmB;;IAEnB,0BAA0B;;IAE1B,8BAA8B;;IAE9B,2DAA2D;;IAE3D,2BAA2B;;IAE3B,2BAA2B;;IAE3B,2DAA2D;;IAE3D,mCAAmC;;IAEnC,mCAAmC;;IAEnC,oCAAoC;;IAEpC,mCAAmC;;IAEnC,uBAAuB;;IAEvB,sBAAsB;;IAEtB,0BAA0B;;CAElB,CAAC;AAwBX;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAW5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D"}
1
+ {"version":3,"file":"bases.d.ts","sourceRoot":"","sources":["../../src/bases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;;GAKG;AACH,eAAO,MAAM,KAAK;IAChB,mBAAmB;;IAEnB,wCAAwC;;IAExC,wCAAwC;;IAExC,mEAAmE;;IAEnE,2DAA2D;;IAE3D,2BAA2B;;IAE3B,2BAA2B;;IAE3B,2DAA2D;;IAE3D,6CAA6C;;IAE7C,sDAAsD;;IAEtD,oCAAoC;;IAEpC,mCAAmC;;IAEnC,yEAAyE;;IAEzE,qEAAqE;;IAErE,4FAA4F;;CAEpF,CAAC;AAKX;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;IAOhB;;;;;;OAMG;;;;;;;;;;;;IAQH,6DAA6D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAgB7D,6DAA6D;;;;;;;;;;;;;;;;IAM7D,2EAA2E;;;;;;IAE3E,yEAAyE;;;;;;;;;;;;;;;;;;;;;;CAQ7B,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,KAAK,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CASjE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D"}