@chainfuse/helpers 3.5.5 → 3.6.0

package/README.md

@@ -15,3 +15,13 @@ import helpers from '@chainfuse/helpers';
 
 // TODO: DEMONSTRATE API
 ```
+
+## UUIDv8
+
+Based on UUIDv7 but with added values to prevent unnecessary lookups
+
+`01f3ffff-fc18-8bb7-9120-cabc55668d92`
+
+| 01f3ffff-fc18                             | 8            | bb7                               | 9                                | 12                                       | 0           | cabc55668d92   |
+| ----------------------------------------- | ------------ | --------------------------------- | -------------------------------- | ---------------------------------------- | ----------- | -------------- |
+| 48bit Timestamp (Unix epoch milliseconds) | UUID Version | Suffix random (`000` if director) | variant (2 bits) + 2 random bits | `DOCombinedLocations` (`00` if anywhere) | `ShardType` | 48 random bits |

package/dist/buffers.d.mts

@@ -1,5 +1,7 @@
 import type { UndefinedProperties } from '@chainfuse/types';
-import type { PrefixedUuid, UuidExport } from '@chainfuse/types/d1';
+import type { PrefixedUuid, UuidExport, UUIDExtract } from '@chainfuse/types/d1';
+import type { z } from 'zod/v4';
+import type { Version8Options } from './uuid8.mjs';
 export type UuidExportBlobInput = Buffer | UuidExport['blob'];
 export declare class BufferHelpers {
     static bigintToBuffer(number: bigint): Promise<ArrayBuffer>;
@@ -9,7 +11,16 @@ export declare class BufferHelpers {
     static bufferToHex(buffer: UuidExportBlobInput): Promise<string>;
     static base64ToBuffer(rawBase64: string): Promise<ArrayBuffer>;
     static bufferToBase64(buffer: UuidExportBlobInput, urlSafe: boolean): Promise<string>;
+    /**
+     * @deprecated Use `BufferHelpers.generateUuid7` instead
+     */
     static get generateUuid(): Promise<UuidExport>;
+    static get v7OptionsBase(): Promise<z.ZodObject<{
+        msecs: z.ZodOptional<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodDate, z.ZodTransform<number, Date>>]>>;
+        seq: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strip>>;
+    static generateUuid7(_options?: z.input<Awaited<typeof this.v7OptionsBase>>): Promise<UuidExport>;
+    static generateUuid8(options?: Omit<Version8Options, 'random' | 'rng'>): Promise<UuidExport>;
     static uuidConvert(input: undefined): Promise<UndefinedProperties<UuidExport>>;
     static uuidConvert(prefixedUtf: PrefixedUuid): Promise<UuidExport>;
     static uuidConvert(input: UuidExport['utf8']): Promise<UuidExport>;
@@ -17,4 +28,11 @@ export declare class BufferHelpers {
     static uuidConvert(input: UuidExportBlobInput): Promise<UuidExport>;
     static uuidConvert(input: UuidExport['base64']): Promise<UuidExport>;
     static uuidConvert(input: UuidExport['base64url']): Promise<UuidExport>;
+    static uuidExtractor(input: undefined): Promise<UUIDExtract>;
+    static uuidExtractor(prefixedUtf: PrefixedUuid): Promise<UUIDExtract>;
+    static uuidExtractor(input: UuidExport['utf8']): Promise<UUIDExtract>;
+    static uuidExtractor(input: UuidExport['hex']): Promise<UUIDExtract>;
+    static uuidExtractor(input: UuidExportBlobInput): Promise<UUIDExtract>;
+    static uuidExtractor(input: UuidExport['base64']): Promise<UUIDExtract>;
+    static uuidExtractor(input: UuidExport['base64url']): Promise<UUIDExtract>;
 }

package/dist/buffers.mjs

@@ -36,9 +36,55 @@ export class BufferHelpers {
     static bufferToBase64(buffer, urlSafe) {
         return BufferHelpersInternals.node_bufferToBase64(buffer, urlSafe).catch(() => BufferHelpersInternals.browser_bufferToBase64(buffer, urlSafe));
     }
+    /**
+     * @deprecated Use `BufferHelpers.generateUuid7` instead
+     */
     static get generateUuid() {
-        return Promise.all([CryptoHelpers.secretBytes(16), import('uuid')]).then(([random, { v7: uuidv7 }]) => {
-            const uuid = uuidv7({ random });
+        return this.generateUuid7();
+    }
+    static get v7OptionsBase() {
+        return import('zod/v4').then(({ z }) => z.object({
+            /**
+             * RFC "timestamp" field
+             */
+            msecs: z
+                .union([
+                z.int().nonnegative(),
+                // Allow converting from Date object
+                z.date().transform((date) => date.getTime()),
+            ])
+                .optional(),
+            /**
+             * 32-bit sequence Number between 0 - 0xffffffff. This may be provided to help ensure uniqueness for UUIDs generated within the same millisecond time interval. Default = random value.
+             */
+            seq: z.int().min(0).max(0xffffffff).optional(),
+        }));
+    }
+    static generateUuid7(_options) {
+        return Promise.all([
+            //
+            import('uuid'),
+            this.v7OptionsBase.then((schema) => schema.parseAsync(_options ?? {})),
+            CryptoHelpers.secretBytes(16),
+        ]).then(([{ v7: uuidv7 }, options, random]) => {
+            const uuid = uuidv7({ msecs: options.msecs, random, seq: options.seq });
+            const uuidHex = uuid.replaceAll('-', '');
+            return this.hexToBuffer(uuidHex).then((blob) => Promise.all([this.bufferToBase64(blob, false), this.bufferToBase64(blob, true)]).then(([base64, base64url]) => ({
+                utf8: uuid,
+                hex: uuidHex,
+                blob,
+                base64,
+                base64url,
+            })));
+        });
+    }
+    static generateUuid8(options) {
+        return Promise.all([import('./uuid8.mjs'), CryptoHelpers.secretBytes(16)]).then(([{ v8: uuidv8 }, random]) => {
+            const uuid = uuidv8({
+                // @ts-expect-error they're the exact same
+                random,
+                ...options,
+            });
             const uuidHex = uuid.replaceAll('-', '');
             return this.hexToBuffer(uuidHex).then((blob) => Promise.all([this.bufferToBase64(blob, false), this.bufferToBase64(blob, true)]).then(([base64, base64url]) => ({
                 utf8: uuid,
@@ -134,4 +180,49 @@ export class BufferHelpers {
             base64url: undefined,
         }))();
     }
+    // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+    static uuidExtractor(input) {
+        return Promise.all([
+            import('zod/v4'),
+            this.uuidConvert(
+            // @ts-expect-error it's the same type
+            input),
+        ]).then(async ([{ z }, { utf8, hex: _hex }]) => {
+            const { success: hexSuccess, data: hex } = z.hex().length(32).safeParse(_hex);
+            if (hexSuccess) {
+                const { success: utf8v7Success } = z.uuid({ version: 'v7' }).safeParse(utf8);
+                const { success: utf8v8Success } = z.uuid({ version: 'v8' }).safeParse(utf8);
+                if (utf8v7Success || utf8v8Success) {
+                    const date = new Date(Number(BigInt(`0x${hex.substring(0, 12)}`)));
+                    if (utf8v8Success) {
+                        const suffix_hex = hex.substring(13, 16);
+                        const suffix_buffer = await BufferHelpers.hexToBuffer(suffix_hex);
+                        return {
+                            date,
+                            location: parseInt(hex.slice(17, 19), 16),
+                            shardType: parseInt(hex.slice(19, 20), 16),
+                            suffix: suffix_hex === '000'
+                                ? undefined
+                                : {
+                                    hex: suffix_hex,
+                                    base64: await BufferHelpers.bufferToBase64(suffix_buffer, false),
+                                    base64url: await BufferHelpers.bufferToBase64(suffix_buffer, true),
+                                },
+                        };
+                    }
+                    else {
+                        return {
+                            date,
+                        };
+                    }
+                }
+                else {
+                    throw new Error('Unsupported UUID version provided');
+                }
+            }
+            else {
+                throw new Error('Invalid UUID provided');
+            }
+        });
+    }
 }

package/dist/crypto.mjs

@@ -5,7 +5,9 @@ export class CryptoHelpers {
         return CryptoHelpersInternals.node_secretBytes(byteSize).catch(() => CryptoHelpersInternals.browser_secretBytes(byteSize));
     }
     static base16secret(secretLength) {
-        return this.secretBytes(secretLength / 2).then((bytes) => BufferHelpers.bufferToHex(bytes.buffer));
+        return this.secretBytes(Math.ceil(secretLength / 2))
+            .then((bytes) => BufferHelpers.bufferToHex(bytes.buffer))
+            .then((hex) => hex.substring(0, secretLength));
     }
     static base62secret(secretLength) {
         const LOWER_CHAR_SET = 'abcdefghijklmnopqrstuvwxyz';

package/dist/net.d.mts

@@ -89,26 +89,26 @@ export declare class NetHelpers {
              */
             webp: z3.ZodOptional<z3.ZodBoolean>;
         }, "strip", z3.ZodTypeAny, {
-            apps: boolean;
             cacheEverything: boolean;
-            mirage: boolean;
             scrapeShield: boolean;
+            apps: boolean;
+            mirage: boolean;
             cacheKey?: string | undefined;
             cacheTags?: [string, ...string[]] | undefined;
             cacheTtl?: number | undefined;
             cacheTtlByStatus?: Record<string, number> | undefined;
-            polish?: "lossy" | "lossless" | "off" | undefined;
+            polish?: "off" | "lossy" | "lossless" | undefined;
             webp?: boolean | undefined;
         }, {
-            apps?: boolean | undefined;
             cacheEverything?: boolean | undefined;
             cacheKey?: string | undefined;
             cacheTags?: [string, ...string[]] | undefined;
             cacheTtl?: number | undefined;
             cacheTtlByStatus?: Record<string, number> | undefined;
-            mirage?: boolean | undefined;
-            polish?: "lossy" | "lossless" | "off" | undefined;
             scrapeShield?: boolean | undefined;
+            apps?: boolean | undefined;
+            mirage?: boolean | undefined;
+            polish?: "off" | "lossy" | "lossless" | undefined;
             webp?: boolean | undefined;
         }>>;
     }, "strip", z3.ZodTypeAny, {
@@ -119,15 +119,15 @@ export declare class NetHelpers {
             custom?: ((...args: unknown[]) => void | Promise<void>) | undefined;
         };
         cf: {
-            apps: boolean;
             cacheEverything: boolean;
-            mirage: boolean;
             scrapeShield: boolean;
+            apps: boolean;
+            mirage: boolean;
             cacheKey?: string | undefined;
             cacheTags?: [string, ...string[]] | undefined;
             cacheTtl?: number | undefined;
             cacheTtlByStatus?: Record<string, number> | undefined;
-            polish?: "lossy" | "lossless" | "off" | undefined;
+            polish?: "off" | "lossy" | "lossless" | undefined;
             webp?: boolean | undefined;
         };
     }, {
@@ -138,15 +138,15 @@ export declare class NetHelpers {
             color?: boolean | undefined;
         } | undefined;
         cf?: {
-            apps?: boolean | undefined;
             cacheEverything?: boolean | undefined;
             cacheKey?: string | undefined;
             cacheTags?: [string, ...string[]] | undefined;
             cacheTtl?: number | undefined;
             cacheTtlByStatus?: Record<string, number> | undefined;
-            mirage?: boolean | undefined;
-            polish?: "lossy" | "lossless" | "off" | undefined;
             scrapeShield?: boolean | undefined;
+            apps?: boolean | undefined;
+            mirage?: boolean | undefined;
+            polish?: "off" | "lossy" | "lossless" | undefined;
             webp?: boolean | undefined;
         } | undefined;
     }>>>;

package/dist/uuid8.d.mts

@@ -0,0 +1,37 @@
+import { DOCombinedLocations } from '@chainfuse/types';
+import { ShardType } from '@chainfuse/types/d0';
+import { z } from 'zod/v4';
+export declare const v8Options: z.ZodUnion<readonly [z.ZodObject<{
+    msecs: z.ZodOptional<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodDate, z.ZodTransform<number, Date>>]>>;
+    seq: z.ZodOptional<z.ZodInt>;
+    location: z.ZodUnion<readonly [z.ZodDefault<z.ZodCustomStringFormat<"hex">>, z.ZodPipe<z.ZodDefault<z.ZodEnum<typeof DOCombinedLocations>>, z.ZodTransform<string, DOCombinedLocations>>]>;
+    shardType: z.ZodUnion<readonly [z.ZodDefault<z.ZodCustomStringFormat<"hex">>, z.ZodPipe<z.ZodDefault<z.ZodEnum<typeof ShardType>>, z.ZodTransform<string, ShardType>>]>;
+    suffix: z.ZodUnion<readonly [z.ZodDefault<z.ZodCustomStringFormat<"hex">>, z.ZodPipe<z.ZodDefault<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>, z.ZodTransform<string, Uint8Array<ArrayBuffer>>>]>;
+    random: z.ZodOptional<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+}, z.core.$strip>, z.ZodObject<{
+    msecs: z.ZodOptional<z.ZodUnion<readonly [z.ZodInt, z.ZodPipe<z.ZodDate, z.ZodTransform<number, Date>>]>>;
+    seq: z.ZodOptional<z.ZodInt>;
+    location: z.ZodUnion<readonly [z.ZodDefault<z.ZodCustomStringFormat<"hex">>, z.ZodPipe<z.ZodDefault<z.ZodEnum<typeof DOCombinedLocations>>, z.ZodTransform<string, DOCombinedLocations>>]>;
+    shardType: z.ZodUnion<readonly [z.ZodDefault<z.ZodCustomStringFormat<"hex">>, z.ZodPipe<z.ZodDefault<z.ZodEnum<typeof ShardType>>, z.ZodTransform<string, ShardType>>]>;
+    suffix: z.ZodUnion<readonly [z.ZodDefault<z.ZodCustomStringFormat<"hex">>, z.ZodPipe<z.ZodDefault<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>, z.ZodTransform<string, Uint8Array<ArrayBuffer>>>]>;
+    rng: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [], null>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>>;
+}, z.core.$strip>]>;
+export type Version8Options = z.input<typeof v8Options>;
+/**
+ * Generates a UUID version 8 with custom fields for location, shard type, and suffix.
+ *
+ * This function creates a UUID v8 by starting with a UUID v7 and then injecting custom fields into specific positions to encode regional information, shard types, and additional suffixes for distributed system identification.
+ *
+ * @param options - Configuration options for UUID generation
+ * @param options.msecs - RFC "timestamp" field - milliseconds since epoch or Date object
+ * @param options.seq - 32-bit sequence number (0 - 0xffffffff) for uniqueness within same millisecond
+ * @param options.location - Location identifier as hex string or DOCombinedLocations enum
+ * @param options.shardType - Shard type as hex string or ShardType enum
+ * @param options.suffix - Custom suffix as hex string or Uint8Array of 2 bytes
+ * @param options.random - Array of 16 random bytes for UUID generation
+ * @param options.rng - Alternative random number generator function
+ *
+ * @returns A UUID v8 string with embedded location, shard type, and suffix information
+ */
+export declare function v8(_options?: Version8Options): string;
+export default v8;

package/dist/uuid8.mjs

@@ -0,0 +1,100 @@
+import { DOCombinedLocations } from '@chainfuse/types';
+import { ShardType } from '@chainfuse/types/d0';
+import { v7 } from 'uuid';
+import { z } from 'zod/v4';
+import { BufferHelpersInternals } from "./bufferInternals.mjs";
+const v8OptionsBase = z.object({
+    /**
+     * RFC "timestamp" field
+     */
+    msecs: z
+        .union([
+        z.int().nonnegative(),
+        // Allow converting from Date object
+        z.date().transform((date) => date.getTime()),
+    ])
+        .optional(),
+    /**
+     * 32-bit sequence Number between 0 - 0xffffffff. This may be provided to help ensure uniqueness for UUIDs generated within the same millisecond time interval. Default = random value.
+     */
+    seq: z.int().min(0).max(0xffffffff).optional(),
+    location: z.union([
+        //
+        z.hex().length(2).default('00'),
+        z
+            .enum(DOCombinedLocations)
+            .default(DOCombinedLocations.none)
+            .transform((r) => r.toString(16).padStart(2, '0').slice(-2)),
+    ]),
+    shardType: z.union([
+        //
+        z.hex().length(1).default('0'),
+        z
+            .enum(ShardType)
+            .default(ShardType.Director)
+            .transform((st) => st.toString(16).padStart(1, '0')),
+    ]),
+    suffix: z.union([
+        z.hex().length(3).default('000'),
+        // It's technically 1.5 bytes, but we round up to nearest integer
+        z
+            .instanceof(Uint8Array)
+            .refine((arr) => arr.byteLength === 2, { message: 'suffix must be a Uint8Array of 2 bytes' })
+            .default(new Uint8Array(2))
+            .transform((arr) => BufferHelpersInternals.browser_bufferToHex(arr.buffer).padStart(3, '0').slice(-3)),
+    ]),
+});
+export const v8Options = z.union([
+    v8OptionsBase.extend({
+        /**
+         * Array of 16 random bytes (0-255) used to generate other fields
+         */
+        random: z
+            .instanceof(Uint8Array)
+            .refine((arr) => arr.byteLength === 16, { message: '`random` must be a Uint8Array of 16 random bytes' })
+            .optional(),
+    }),
+    v8OptionsBase.extend({
+        /**
+         * Alternative to options.random, a Function that returns an Array of 16 random bytes (0-255)
+         */
+        rng: z
+            .function({
+            input: [],
+            output: z.instanceof(Uint8Array).refine((arr) => arr.byteLength === 16, { message: '`random` must be a Uint8Array of 16 random bytes' }),
+        })
+            .optional(),
+    }),
+]);
+function replaceByIndex(input, start, end, replacement) {
+    return input.slice(0, start) + replacement + input.slice(end);
+}
+/**
+ * Generates a UUID version 8 with custom fields for location, shard type, and suffix.
+ *
+ * This function creates a UUID v8 by starting with a UUID v7 and then injecting custom fields into specific positions to encode regional information, shard types, and additional suffixes for distributed system identification.
+ *
+ * @param options - Configuration options for UUID generation
+ * @param options.msecs - RFC "timestamp" field - milliseconds since epoch or Date object
+ * @param options.seq - 32-bit sequence number (0 - 0xffffffff) for uniqueness within same millisecond
+ * @param options.location - Location identifier as hex string or DOCombinedLocations enum
+ * @param options.shardType - Shard type as hex string or ShardType enum
+ * @param options.suffix - Custom suffix as hex string or Uint8Array of 2 bytes
+ * @param options.random - Array of 16 random bytes for UUID generation
+ * @param options.rng - Alternative random number generator function
+ *
+ * @returns A UUID v8 string with embedded location, shard type, and suffix information
+ */
+export function v8(_options) {
+    const options = v8Options.parse(_options ?? {});
+    // 36 character string including hyphens
+    const uuid7 = v7(options);
+    // Swap version
+    const uuid8 = replaceByIndex(uuid7, 14, 15, '8');
+    // Inject
+    const uuid8Suffix = replaceByIndex(uuid8, 15, 18, options.suffix);
+    const uuid8SuffixLocation = replaceByIndex(uuid8Suffix, 20, 22, options.location);
+    const uuid8SuffixLocationShard = replaceByIndex(uuid8SuffixLocation, 22, 23, options.shardType);
+    return uuid8SuffixLocationShard;
+}
+export default v8;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chainfuse/helpers",
-	"version": "3.5.5",
+	"version": "3.6.0",
 	"description": "",
 	"author": "ChainFuse",
 	"homepage": "https://github.com/ChainFuse/packages/tree/main/packages/helpers#readme",
@@ -72,22 +72,26 @@
 		"./net": {
 			"import": "./dist/net.mjs",
 			"types": "./dist/net.d.mts"
+		},
+		"./uuid8": {
+			"import": "./dist/uuid8.mjs",
+			"types": "./dist/uuid8.d.mts"
 		}
 	},
 	"prettier": "@demosjarco/prettier-config",
 	"dependencies": {
-		"@chainfuse/types": "^2.11.8",
+		"@chainfuse/types": "^2.12.0",
 		"@discordjs/rest": "^2.6.0",
-		"chalk": "^5.6.0",
-		"cloudflare": "^4.5.0",
+		"chalk": "^5.6.2",
+		"cloudflare": "^5.0.0",
 		"drizzle-orm": "^0.44.5",
-		"strip-ansi": "^7.1.0",
-		"uuid": "^11.1.0",
+		"strip-ansi": "^7.1.2",
+		"uuid": "^13.0.0",
 		"zod": "^4.1.5"
 	},
 	"devDependencies": {
-		"@cloudflare/workers-types": "^4.20250903.0",
-		"@types/node": "^22.18.0"
+		"@cloudflare/workers-types": "^4.20250909.0",
+		"@types/node": "^22.18.1"
 	},
-	"gitHead": "83cf299d3a269f53051512f24470cdb80e167209"
+	"gitHead": "fe95f7c82786f19dda1e465f38b19be98613f981"
 }