@anizoptera/uuid-slug 0.3.0 → 0.5.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 (202) hide show
  1. package/LICENSE +54 -31
  2. package/README.md +373 -324
  3. package/dist/alphabet.d.ts +5 -17
  4. package/dist/alphabet.d.ts.map +1 -1
  5. package/dist/alphabet.js +146 -112
  6. package/dist/alphabet.js.map +1 -1
  7. package/dist/base64url-name.d.ts +7 -0
  8. package/dist/base64url-name.d.ts.map +1 -0
  9. package/dist/base64url-name.js +8 -0
  10. package/dist/base64url-name.js.map +1 -0
  11. package/dist/errors.d.ts +50 -9
  12. package/dist/errors.d.ts.map +1 -1
  13. package/dist/errors.js +145 -63
  14. package/dist/errors.js.map +1 -1
  15. package/dist/feistel.js +29 -95
  16. package/dist/feistel.js.map +1 -1
  17. package/dist/generation-options.js +20 -0
  18. package/dist/generation-options.js.map +1 -0
  19. package/dist/index.d.ts +22 -10
  20. package/dist/index.js +21 -9
  21. package/dist/instant.js +83 -0
  22. package/dist/instant.js.map +1 -0
  23. package/dist/mask-handle.d.ts +16 -0
  24. package/dist/mask-handle.d.ts.map +1 -0
  25. package/dist/mask-handle.js +60 -0
  26. package/dist/mask-handle.js.map +1 -0
  27. package/dist/mask.d.ts +27 -0
  28. package/dist/mask.d.ts.map +1 -0
  29. package/dist/mask.js +151 -95
  30. package/dist/mask.js.map +1 -1
  31. package/dist/masking-codec-protocol.js +23 -0
  32. package/dist/masking-codec-protocol.js.map +1 -0
  33. package/dist/masking-codec-types.d.ts +245 -0
  34. package/dist/masking-codec-types.d.ts.map +1 -0
  35. package/dist/masking-codec.d.ts +19 -0
  36. package/dist/masking-codec.d.ts.map +1 -0
  37. package/dist/masking-codec.js +391 -0
  38. package/dist/masking-codec.js.map +1 -0
  39. package/dist/migration.js +114 -51
  40. package/dist/migration.js.map +1 -1
  41. package/dist/node/runtime.js +39 -0
  42. package/dist/node/runtime.js.map +1 -0
  43. package/dist/payload.d.ts +7 -0
  44. package/dist/payload.d.ts.map +1 -0
  45. package/dist/payload.js +118 -0
  46. package/dist/payload.js.map +1 -0
  47. package/dist/runtime/pool.js +21 -46
  48. package/dist/runtime/pool.js.map +1 -1
  49. package/dist/runtime/portable.js +27 -0
  50. package/dist/runtime/portable.js.map +1 -0
  51. package/dist/sentinel.js +10 -0
  52. package/dist/sentinel.js.map +1 -0
  53. package/dist/siphash.js +20 -99
  54. package/dist/siphash.js.map +1 -1
  55. package/dist/slug.d.ts +169 -0
  56. package/dist/slug.d.ts.map +1 -0
  57. package/dist/slug.js +268 -0
  58. package/dist/slug.js.map +1 -0
  59. package/dist/timestamp.d.ts +19 -0
  60. package/dist/timestamp.d.ts.map +1 -0
  61. package/dist/timestamp.js +44 -0
  62. package/dist/timestamp.js.map +1 -0
  63. package/dist/types.d.ts +480 -200
  64. package/dist/types.d.ts.map +1 -1
  65. package/dist/types.js +8 -0
  66. package/dist/types.js.map +1 -0
  67. package/dist/uuid-value-protocol.js +46 -0
  68. package/dist/uuid-value-protocol.js.map +1 -0
  69. package/dist/uuid-value.d.ts +17 -0
  70. package/dist/uuid-value.d.ts.map +1 -0
  71. package/dist/uuid-value.js +127 -0
  72. package/dist/uuid-value.js.map +1 -0
  73. package/dist/uuid.d.ts +51 -64
  74. package/dist/uuid.d.ts.map +1 -1
  75. package/dist/uuid.js +203 -199
  76. package/dist/uuid.js.map +1 -1
  77. package/dist/v4-slug.d.ts +16 -0
  78. package/dist/v4-slug.d.ts.map +1 -0
  79. package/dist/v4-slug.js +16 -0
  80. package/dist/v4-slug.js.map +1 -0
  81. package/dist/v4.d.ts +42 -0
  82. package/dist/v4.d.ts.map +1 -0
  83. package/dist/v4.js +85 -0
  84. package/dist/v4.js.map +1 -0
  85. package/dist/v7-bounds.d.ts +36 -0
  86. package/dist/v7-bounds.d.ts.map +1 -0
  87. package/dist/v7-bounds.js +49 -0
  88. package/dist/v7-bounds.js.map +1 -0
  89. package/dist/v7-generator-input.js +75 -0
  90. package/dist/v7-generator-input.js.map +1 -0
  91. package/dist/v7-generator.d.ts +43 -0
  92. package/dist/v7-generator.d.ts.map +1 -0
  93. package/dist/v7-generator.js +105 -0
  94. package/dist/v7-generator.js.map +1 -0
  95. package/dist/v7-keyless.d.ts +46 -0
  96. package/dist/v7-keyless.d.ts.map +1 -0
  97. package/dist/v7-keyless.js +106 -0
  98. package/dist/v7-keyless.js.map +1 -0
  99. package/dist/v7-payload.js +54 -0
  100. package/dist/v7-payload.js.map +1 -0
  101. package/dist/v7-slug.d.ts +46 -0
  102. package/dist/v7-slug.d.ts.map +1 -0
  103. package/dist/v7-slug.js +127 -0
  104. package/dist/v7-slug.js.map +1 -0
  105. package/dist/v7-timestamp.js +9 -0
  106. package/dist/v7-timestamp.js.map +1 -0
  107. package/dist/v7-value-options.js +28 -0
  108. package/dist/v7-value-options.js.map +1 -0
  109. package/dist/v7-value.d.ts +23 -0
  110. package/dist/v7-value.d.ts.map +1 -0
  111. package/dist/v7-value.js +31 -0
  112. package/dist/v7-value.js.map +1 -0
  113. package/dist/v7.js +127 -171
  114. package/dist/v7.js.map +1 -1
  115. package/package.json +15 -8
  116. package/src/alphabet.ts +456 -27
  117. package/src/base64url-name.ts +5 -0
  118. package/src/errors.ts +373 -37
  119. package/src/feistel.ts +69 -56
  120. package/src/generation-options.ts +48 -0
  121. package/src/index.ts +134 -80
  122. package/src/instant.ts +196 -0
  123. package/src/keyless.ts +7 -134
  124. package/src/mask-handle.ts +141 -0
  125. package/src/mask.ts +354 -129
  126. package/src/masking-codec-protocol.ts +29 -0
  127. package/src/masking-codec-types.ts +380 -0
  128. package/src/masking-codec.ts +923 -0
  129. package/src/migration.ts +195 -42
  130. package/src/payload.ts +321 -0
  131. package/src/runtime/bun.ts +30 -49
  132. package/src/runtime/node.ts +43 -24
  133. package/src/runtime/pool.ts +49 -21
  134. package/src/runtime/portable.ts +68 -0
  135. package/src/runtime/types.ts +23 -35
  136. package/src/sentinel.ts +13 -0
  137. package/src/siphash.ts +5 -4
  138. package/src/slug.ts +884 -0
  139. package/src/timestamp.ts +122 -0
  140. package/src/types.ts +759 -205
  141. package/src/uuid-value-protocol.ts +77 -0
  142. package/src/uuid-value.ts +341 -0
  143. package/src/uuid.ts +514 -234
  144. package/src/v4-slug.ts +27 -0
  145. package/src/v4.ts +234 -0
  146. package/src/v7-bounds.ts +171 -0
  147. package/src/v7-generator-input.ts +169 -0
  148. package/src/v7-generator.ts +245 -0
  149. package/src/v7-keyless.ts +354 -0
  150. package/src/v7-payload.ts +121 -0
  151. package/src/v7-slug.ts +293 -0
  152. package/src/v7-timestamp.ts +21 -0
  153. package/src/v7-value-options.ts +62 -0
  154. package/src/v7-value.ts +54 -0
  155. package/src/v7.ts +377 -200
  156. package/dist/base64url.d.ts +0 -20
  157. package/dist/base64url.d.ts.map +0 -1
  158. package/dist/base64url.js +0 -33
  159. package/dist/base64url.js.map +0 -1
  160. package/dist/codec.d.ts +0 -17
  161. package/dist/codec.d.ts.map +0 -1
  162. package/dist/codec.js +0 -192
  163. package/dist/codec.js.map +0 -1
  164. package/dist/keyless.d.ts +0 -31
  165. package/dist/keyless.d.ts.map +0 -1
  166. package/dist/keyless.js +0 -93
  167. package/dist/keyless.js.map +0 -1
  168. package/dist/legacy-mask.js +0 -55
  169. package/dist/legacy-mask.js.map +0 -1
  170. package/dist/node/alphabet.js +0 -130
  171. package/dist/node/base64url.js +0 -31
  172. package/dist/node/codec.js +0 -190
  173. package/dist/node/errors.js +0 -78
  174. package/dist/node/feistel.js +0 -103
  175. package/dist/node/index.js +0 -10
  176. package/dist/node/keyless.js +0 -91
  177. package/dist/node/legacy-mask.js +0 -53
  178. package/dist/node/mask.js +0 -106
  179. package/dist/node/migration.js +0 -64
  180. package/dist/node/runtime/node.js +0 -33
  181. package/dist/node/runtime/pool.js +0 -53
  182. package/dist/node/schema.js +0 -214
  183. package/dist/node/siphash.js +0 -106
  184. package/dist/node/uuid.js +0 -226
  185. package/dist/node/v7.js +0 -185
  186. package/dist/node/yield.js +0 -20
  187. package/dist/runtime/web.js +0 -39
  188. package/dist/runtime/web.js.map +0 -1
  189. package/dist/schema.d.ts +0 -20
  190. package/dist/schema.d.ts.map +0 -1
  191. package/dist/schema.js +0 -216
  192. package/dist/schema.js.map +0 -1
  193. package/dist/v7.d.ts +0 -12
  194. package/dist/v7.d.ts.map +0 -1
  195. package/dist/yield.js +0 -22
  196. package/dist/yield.js.map +0 -1
  197. package/src/base64url.ts +0 -41
  198. package/src/codec.ts +0 -320
  199. package/src/legacy-mask.ts +0 -25
  200. package/src/runtime/web.ts +0 -48
  201. package/src/schema.ts +0 -300
  202. package/src/yield.ts +0 -22
@@ -0,0 +1,122 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+
3
+ import {
4
+ findUnknownOption,
5
+ INVALID_TIMESTAMP,
6
+ INVALID_UUID_VERSION,
7
+ TIMESTAMP_OUTSIDE_WINDOW,
8
+ normalizeUuidStringInput,
9
+ UuidSlugError,
10
+ } from "./errors.ts";
11
+ import { UUID_TEXT_LOWERCASE } from "./types.ts";
12
+ import type {
13
+ UuidTextCase,
14
+ UuidTextCaseArguments,
15
+ UuidV7StringFor,
16
+ UuidV7StringInput,
17
+ UuidV7TimestampWindow,
18
+ } from "./types.ts";
19
+ import {
20
+ formatUuidBytesUnchecked,
21
+ resolveUuidTextCase,
22
+ isUuidV7Bytes,
23
+ uuidTimestampFromBytesUnchecked,
24
+ uuidStringToBytes,
25
+ } from "./uuid.ts";
26
+
27
+ const TIMESTAMP_WINDOW_OPTIONS = {
28
+ maxTimestampDeltaMs: true,
29
+ referenceUnixMs: true,
30
+ } as const satisfies Record<keyof UuidV7TimestampWindow, true>;
31
+
32
+ /** Decode before reading the reference time so validation performs one clock observation. */
33
+ export function validateTimestampBytes(
34
+ bytes: Uint8Array,
35
+ window: UuidV7TimestampWindow,
36
+ ): undefined | UuidSlugError {
37
+ if (!isUuidV7Bytes(bytes))
38
+ return new UuidSlugError(
39
+ INVALID_UUID_VERSION,
40
+ "Timestamp validation requires an RFC-variant UUIDv7.",
41
+ );
42
+ const timestamp = uuidTimestampFromBytesUnchecked(bytes, 0);
43
+ let maxTimestampDeltaMs: number;
44
+ let referenceUnixMs: number;
45
+ try {
46
+ if (typeof window !== "object" || window === null || Array.isArray(window))
47
+ return new UuidSlugError(INVALID_TIMESTAMP, "Timestamp window must be an object.");
48
+ const unknown = findUnknownOption(window, TIMESTAMP_WINDOW_OPTIONS);
49
+ if (unknown !== undefined)
50
+ return new UuidSlugError(INVALID_TIMESTAMP, `Unknown timestamp window option: ${unknown}.`);
51
+ maxTimestampDeltaMs = window.maxTimestampDeltaMs;
52
+ referenceUnixMs = window.referenceUnixMs ?? Date.now();
53
+ } catch (cause) {
54
+ return new UuidSlugError(INVALID_TIMESTAMP, "Timestamp window could not be read.", { cause });
55
+ }
56
+ if (!Number.isFinite(maxTimestampDeltaMs) || maxTimestampDeltaMs < 0)
57
+ return new UuidSlugError(
58
+ INVALID_TIMESTAMP,
59
+ "maxTimestampDeltaMs must be a finite, nonnegative number of milliseconds.",
60
+ );
61
+ if (!Number.isFinite(referenceUnixMs))
62
+ return new UuidSlugError(
63
+ INVALID_TIMESTAMP,
64
+ "referenceUnixMs must be a finite number of Unix milliseconds.",
65
+ );
66
+ if (
67
+ timestamp < referenceUnixMs - maxTimestampDeltaMs ||
68
+ timestamp > referenceUnixMs + maxTimestampDeltaMs
69
+ )
70
+ return new UuidSlugError(
71
+ TIMESTAMP_OUTSIDE_WINDOW,
72
+ `UUIDv7 timestamp ${timestamp} is outside ${referenceUnixMs - maxTimestampDeltaMs}..${referenceUnixMs + maxTimestampDeltaMs} Unix milliseconds.`,
73
+ );
74
+ return undefined;
75
+ }
76
+
77
+ /**
78
+ * Validate accepted UUIDv7 text and return its normalized hyphenated spelling when its timestamp is
79
+ * inside the inclusive symmetric window. Return `timestamp_outside_window` when it is not. This checks clock plausibility, not
80
+ * expiry, authentication, replay, or issuance. TypeScript rejects known slug and UUIDv4 values. A
81
+ * preceding `UuidSlugError` is returned unchanged.
82
+ *
83
+ * @param uuid - UUIDv7 text in an accepted spelling to validate and normalize. JavaScript also
84
+ * accepts a genuine `String` object.
85
+ * @param window - Inclusive maximum distance from an explicit or current reference time.
86
+ * @param textCase - Built-in output spelling. Omit for lowercase.
87
+ */
88
+ export function validateUuidV7StringUnixMs<
89
+ Input extends string | UuidSlugError,
90
+ Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE,
91
+ >(
92
+ uuid: UuidV7StringInput<Input>,
93
+ window: UuidV7TimestampWindow,
94
+ ...textCase: UuidTextCaseArguments<Case>
95
+ ): UuidV7StringFor<Case> | UuidSlugError;
96
+ export function validateUuidV7StringUnixMs(
97
+ uuid: unknown,
98
+ window: UuidV7TimestampWindow,
99
+ textCase: UuidTextCase = UUID_TEXT_LOWERCASE,
100
+ ): string | UuidSlugError {
101
+ let uuidText: string;
102
+ if (typeof uuid === "string") {
103
+ uuidText = uuid;
104
+ } else {
105
+ const normalized = normalizeUuidStringInput(uuid);
106
+ if (typeof normalized !== "string") return normalized;
107
+ uuidText = normalized;
108
+ }
109
+ const selectedCase = resolveUuidTextCase(textCase);
110
+ if (selectedCase instanceof Error) return selectedCase;
111
+ const bytes = uuidStringToBytes(uuidText);
112
+ if (bytes instanceof Error) return bytes;
113
+ const valid = validateTimestampBytes(bytes, window);
114
+ if (valid instanceof Error) return valid;
115
+ const alreadySelected =
116
+ uuidText.length === 36 &&
117
+ (selectedCase === UUID_TEXT_LOWERCASE
118
+ ? uuidText === uuidText.toLowerCase()
119
+ : uuidText === uuidText.toUpperCase());
120
+ if (alreadySelected) return uuidText;
121
+ return formatUuidBytesUnchecked(bytes, 0, selectedCase);
122
+ }