@kakilangit/id-generator 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,143 @@
+# @kakilangit/id-generator
+
+WebAssembly bindings for ID Generator tool - Generate UUID, NULID, and NanoID identifiers.
+
+## Overview
+
+This package provides fast ID generation and decoding functionality compiled to WebAssembly from Rust. It supports:
+
+- **UUID v1** (time-based) - Time-based with MAC address
+- **UUID v4** (random) - Randomly generated UUIDs
+- **UUID v6** (time-ordered) - Time-ordered for better database locality
+- **UUID v7** (time-based) - Time-ordered UUIDs with millisecond precision
+- **UUID v8** (custom) - Custom format for experimental use
+- **NULID** (nanosecond ULID) - Lexicographically sortable IDs with nanosecond precision
+- **NanoID** - URL-friendly, cryptographically secure random ID
+
+## Installation
+
+```bash
+npm install @kakilangit/id-generator
+```
+
+## Usage
+
+```javascript
+import init, { generate_ids, decode_id, JsIdFormat, JsIdCase } from '@kakilangit/id-generator';
+
+// Initialize the WASM module
+await init();
+
+// Generate 5 UUID v4 IDs in lowercase
+const uuids = generate_ids(JsIdFormat.UuidV4, 5, JsIdCase.Lower);
+console.log(uuids); // ["a1b2c3d4-...", "e5f6g7h8-...", ...]
+
+// Generate time-based UUID v7
+const uuid7s = generate_ids(JsIdFormat.UuidV7, 1, JsIdCase.Lower);
+
+// Generate NULIDs (nanosecond precision)
+const nulids = generate_ids(JsIdFormat.Nulid, 3, JsIdCase.Upper);
+
+// Generate NanoIDs (URL-safe, 21 characters by default)
+const nanoids = generate_ids(JsIdFormat.NanoId, 5, JsIdCase.Lower);
+
+// Decode an ID to get metadata
+const decoded = decode_id("01hny0qzcw8a5v8z...");
+console.log(decoded.format);     // "NULID"
+console.log(decoded.time);       // "2024-01-15T10:30:45.123456789Z"
+console.log(decoded.timestamp);  // { precision: "ns", value: "1705315845123456789" }
+console.log(decoded.hex);       // Hex representation
+console.log(decoded.bytes);      // Byte representation (colon-separated)
+```
+
+## API
+
+### Functions
+
+#### `generate_ids(format, count, case)`
+Generates multiple IDs of the specified format.
+
+- `format` (JsIdFormat): The ID format to generate
+- `count` (number): Number of IDs to generate (1-10000)
+- `case` (JsIdCase): Case format for alphabetic characters (ignored for NanoID)
+
+Returns: `string[]` - Array of generated IDs
+
+#### `decode_id(id)`
+Decodes an ID string and returns its metadata.
+
+- `id` (string): The ID to decode
+
+Returns `JsDecodedId`:
+- `original`: The original ID string
+- `format`: Detected format name ("UUID v1", "UUID v4", "UUID v6", "UUID v7", "UUID v8", "NULID")
+- `time`: RFC 3339 formatted time string (if time-based: UUID v1, v6, v7, NULID)
+- `timestamp`: Object with `precision` ("ms" or "ns") and `value`
+- `randomness`: Random component as decimal string (if applicable)
+- `hex`: Full ID as hex string
+- `bytes`: Full ID as colon-separated hex bytes
+
+#### `get_available_formats()`
+Returns all available ID format names.
+
+### Enums
+
+#### `JsIdFormat`
+- `UuidV1 = 0` - UUID version 1 (time-based with MAC address)
+- `UuidV4 = 1` - UUID version 4 (random)
+- `UuidV6 = 2` - UUID version 6 (time-ordered for database locality)
+- `UuidV7 = 3` - UUID version 7 (time-based, millisecond precision)
+- `UuidV8 = 4` - UUID version 8 (custom/experimental)
+- `Nulid = 5` - NULID (nanosecond-precision ULID)
+- `NanoId = 6` - NanoID (URL-friendly, cryptographically secure)
+
+#### `JsIdCase`
+- `Lower = 0` - Lowercase output
+- `Upper = 1` - Uppercase output
+
+## ID Format Details
+
+### UUID v1
+- Time-based UUID with MAC address
+- 36 characters (with hyphens)
+- Includes timestamp and MAC address (privacy concern)
+- Example: `6ba7b810-9dad-11d1-80b4-00c04fd430c8`
+
+### UUID v4
+- Randomly generated 128-bit UUID
+- 36 characters (with hyphens)
+- Example: `550e8400-e29b-41d4-a716-446655440000`
+
+### UUID v6
+- Time-ordered UUID for better database index locality
+- 36 characters (with hyphens)
+- Similar to UUID v1 but with reordered bytes
+- Example: `0166e6b8-9dad-7b80-80b4-00c04fd430c8`
+
+### UUID v7
+- Time-ordered UUID with Unix timestamp (milliseconds)
+- 36 characters (with hyphens)
+- Sortable by generation time
+- Example: `018e1234-5678-7abc-8def-0123456789ab`
+
+### UUID v8
+- Custom format for experimental use
+- 36 characters (with hyphens)
+- No specific structure enforced
+- Example: `123e4567-e89b-87c5-d012-3456789abcdef`
+
+### NULID
+- Nanosecond-precision lexicographically sortable ID
+- 26 characters (Crockford Base32)
+- Sortable by generation time with nanosecond precision
+- Example: `01hny0qzcw8a5v8z7g6f4d2b9j`
+
+### NanoID
+- URL-friendly, cryptographically secure random ID
+- Uses unreserved URL characters (A-Za-z0-9_-)
+- Default length: 21 characters
+- Example: `NVUp3WKdn2KwW-8S8XYz`
+
+## License
+
+MIT

package/id_generator.d.ts

@@ -16,10 +16,6 @@ export class JsDecodedId {
      * The detected format name.
      */
     format: string;
-    /**
-     * Full ID as hex string.
-     */
-    hex: string;
     /**
      * The original ID string.
      */
@@ -68,18 +64,34 @@ export enum JsIdCase {
  * ID format options for JavaScript.
  */
 export enum JsIdFormat {
+    /**
+     * UUID version 1 (time-based with MAC address).
+     */
+    UuidV1 = 0,
     /**
      * UUID version 4 (random).
      */
-    UuidV4 = 0,
+    UuidV4 = 1,
+    /**
+     * UUID version 6 (time-ordered for better database locality).
+     */
+    UuidV6 = 2,
+    /**
+     * UUID version 7 (time-based with millisecond precision).
+     */
+    UuidV7 = 3,
     /**
-     * UUID version 7 (time-based).
+     * UUID version 8 (custom format for experimental use).
      */
-    UuidV7 = 1,
+    UuidV8 = 4,
     /**
      * NULID (Nanosecond-precision Universally Lexicographically Sortable Identifier).
      */
-    Nulid = 2,
+    Nulid = 5,
+    /**
+     * `NanoID` (URL-friendly, cryptographically secure random ID).
+     */
+    NanoId = 6,
 }
 
 /**
@@ -130,7 +142,6 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_get_jsdecodedid_bytes: (a: number, b: number) => void;
     readonly __wbg_get_jsdecodedid_format: (a: number, b: number) => void;
-    readonly __wbg_get_jsdecodedid_hex: (a: number, b: number) => void;
     readonly __wbg_get_jsdecodedid_original: (a: number, b: number) => void;
     readonly __wbg_get_jsdecodedid_randomness: (a: number, b: number) => void;
     readonly __wbg_get_jsdecodedid_time: (a: number, b: number) => void;
@@ -139,7 +150,6 @@ export interface InitOutput {
     readonly __wbg_jstimestamp_free: (a: number, b: number) => void;
     readonly __wbg_set_jsdecodedid_bytes: (a: number, b: number, c: number) => void;
     readonly __wbg_set_jsdecodedid_format: (a: number, b: number, c: number) => void;
-    readonly __wbg_set_jsdecodedid_hex: (a: number, b: number, c: number) => void;
     readonly __wbg_set_jsdecodedid_original: (a: number, b: number, c: number) => void;
     readonly __wbg_set_jsdecodedid_randomness: (a: number, b: number, c: number) => void;
     readonly __wbg_set_jsdecodedid_time: (a: number, b: number, c: number) => void;

package/id_generator.js

@@ -61,26 +61,6 @@ export class JsDecodedId {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
-    /**
-     * Full ID as hex string.
-     * @returns {string}
-     */
-    get hex() {
-        let deferred1_0;
-        let deferred1_1;
-        try {
-            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            wasm.__wbg_get_jsdecodedid_hex(retptr, this.__wbg_ptr);
-            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
-            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
-            deferred1_0 = r0;
-            deferred1_1 = r1;
-            return getStringFromWasm0(r0, r1);
-        } finally {
-            wasm.__wbindgen_add_to_stack_pointer(16);
-            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
-        }
-    }
     /**
      * The original ID string.
      * @returns {string}
@@ -167,15 +147,6 @@ export class JsDecodedId {
         const len0 = WASM_VECTOR_LEN;
         wasm.__wbg_set_jsdecodedid_format(this.__wbg_ptr, ptr0, len0);
     }
-    /**
-     * Full ID as hex string.
-     * @param {string} arg0
-     */
-    set hex(arg0) {
-        const ptr0 = passStringToWasm0(arg0, wasm.__wbindgen_export2, wasm.__wbindgen_export3);
-        const len0 = WASM_VECTOR_LEN;
-        wasm.__wbg_set_jsdecodedid_hex(this.__wbg_ptr, ptr0, len0);
-    }
     /**
      * The original ID string.
      * @param {string} arg0
@@ -235,21 +206,37 @@ export const JsIdCase = Object.freeze({
 
 /**
  * ID format options for JavaScript.
- * @enum {0 | 1 | 2}
+ * @enum {0 | 1 | 2 | 3 | 4 | 5 | 6}
  */
 export const JsIdFormat = Object.freeze({
+    /**
+     * UUID version 1 (time-based with MAC address).
+     */
+    UuidV1: 0, "0": "UuidV1",
     /**
      * UUID version 4 (random).
      */
-    UuidV4: 0, "0": "UuidV4",
+    UuidV4: 1, "1": "UuidV4",
+    /**
+     * UUID version 6 (time-ordered for better database locality).
+     */
+    UuidV6: 2, "2": "UuidV6",
     /**
-     * UUID version 7 (time-based).
+     * UUID version 7 (time-based with millisecond precision).
      */
-    UuidV7: 1, "1": "UuidV7",
+    UuidV7: 3, "3": "UuidV7",
+    /**
+     * UUID version 8 (custom format for experimental use).
+     */
+    UuidV8: 4, "4": "UuidV8",
     /**
      * NULID (Nanosecond-precision Universally Lexicographically Sortable Identifier).
      */
-    Nulid: 2, "2": "Nulid",
+    Nulid: 5, "5": "Nulid",
+    /**
+     * `NanoID` (URL-friendly, cryptographically secure random ID).
+     */
+    NanoId: 6, "6": "NanoId",
 });
 
 /**
@@ -414,6 +401,19 @@ export function get_available_formats() {
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
+        __wbg___wbindgen_is_function_0095a73b8b156f76: function(arg0) {
+            const ret = typeof(getObject(arg0)) === 'function';
+            return ret;
+        },
+        __wbg___wbindgen_is_object_5ae8e5880f2c1fbd: function(arg0) {
+            const val = getObject(arg0);
+            const ret = typeof(val) === 'object' && val !== null;
+            return ret;
+        },
+        __wbg___wbindgen_is_string_cd444516edc5b180: function(arg0) {
+            const ret = typeof(getObject(arg0)) === 'string';
+            return ret;
+        },
         __wbg___wbindgen_is_undefined_9e4d92534c42d778: function(arg0) {
             const ret = getObject(arg0) === undefined;
             return ret;
@@ -425,16 +425,43 @@ function __wbg_get_imports() {
             const ret = getObject(arg0).call(getObject(arg1));
             return addHeapObject(ret);
         }, arguments); },
+        __wbg_call_4708e0c13bdc8e95: function() { return handleError(function (arg0, arg1, arg2) {
+            const ret = getObject(arg0).call(getObject(arg1), getObject(arg2));
+            return addHeapObject(ret);
+        }, arguments); },
+        __wbg_crypto_86f2631e91b51511: function(arg0) {
+            const ret = getObject(arg0).crypto;
+            return addHeapObject(ret);
+        },
         __wbg_getRandomValues_1c61fac11405ffdc: function() { return handleError(function (arg0, arg1) {
             globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
         }, arguments); },
         __wbg_getRandomValues_9c5c1b115e142bb8: function() { return handleError(function (arg0, arg1) {
             globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
         }, arguments); },
+        __wbg_getRandomValues_b3f15fcbfabb0f8b: function() { return handleError(function (arg0, arg1) {
+            getObject(arg0).getRandomValues(getObject(arg1));
+        }, arguments); },
+        __wbg_length_32ed9a279acd054c: function(arg0) {
+            const ret = getObject(arg0).length;
+            return ret;
+        },
+        __wbg_msCrypto_d562bbe83e0d4b91: function(arg0) {
+            const ret = getObject(arg0).msCrypto;
+            return addHeapObject(ret);
+        },
         __wbg_new_no_args_1c7c842f08d00ebb: function(arg0, arg1) {
             const ret = new Function(getStringFromWasm0(arg0, arg1));
             return addHeapObject(ret);
         },
+        __wbg_new_with_length_a2c39cbe88fd8ff1: function(arg0) {
+            const ret = new Uint8Array(arg0 >>> 0);
+            return addHeapObject(ret);
+        },
+        __wbg_node_e1f24f89a7336c2e: function(arg0) {
+            const ret = getObject(arg0).node;
+            return addHeapObject(ret);
+        },
         __wbg_now_2c95c9de01293173: function(arg0) {
             const ret = getObject(arg0).now();
             return ret;
@@ -451,6 +478,20 @@ function __wbg_get_imports() {
             const ret = getObject(arg0).performance;
             return addHeapObject(ret);
         },
+        __wbg_process_3975fd6c72f520aa: function(arg0) {
+            const ret = getObject(arg0).process;
+            return addHeapObject(ret);
+        },
+        __wbg_prototypesetcall_bdcdcc5842e4d77d: function(arg0, arg1, arg2) {
+            Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), getObject(arg2));
+        },
+        __wbg_randomFillSync_f8c153b79f285817: function() { return handleError(function (arg0, arg1) {
+            getObject(arg0).randomFillSync(takeObject(arg1));
+        }, arguments); },
+        __wbg_require_b74f47fc2d022fd6: function() { return handleError(function () {
+            const ret = module.require;
+            return addHeapObject(ret);
+        }, arguments); },
         __wbg_static_accessor_GLOBAL_12837167ad935116: function() {
             const ret = typeof global === 'undefined' ? null : global;
             return isLikeNone(ret) ? 0 : addHeapObject(ret);
@@ -467,7 +508,20 @@ function __wbg_get_imports() {
             const ret = typeof window === 'undefined' ? null : window;
             return isLikeNone(ret) ? 0 : addHeapObject(ret);
         },
+        __wbg_subarray_a96e1fef17ed23cb: function(arg0, arg1, arg2) {
+            const ret = getObject(arg0).subarray(arg1 >>> 0, arg2 >>> 0);
+            return addHeapObject(ret);
+        },
+        __wbg_versions_4e31226f5e8dc909: function(arg0) {
+            const ret = getObject(arg0).versions;
+            return addHeapObject(ret);
+        },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
+            // Cast intrinsic for `Ref(Slice(U8)) -> NamedExternref("Uint8Array")`.
+            const ret = getArrayU8FromWasm0(arg0, arg1);
+            return addHeapObject(ret);
+        },
+        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return addHeapObject(ret);

package/package.json

@@ -1,26 +1,30 @@
 {
   "name": "@kakilangit/id-generator",
-  "version": "0.1.0",
-  "description": "WebAssembly bindings for ID Generator tool (UUID v4, UUID v7, NULID)",
   "type": "module",
-  "main": "id_generator.js",
-  "types": "id_generator.d.ts",
+  "collaborators": [
+    "kakilangit"
+  ],
+  "description": "WebAssembly bindings for ID Generator tool",
+  "version": "0.2.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://dev.kakilangit.com"
+  },
   "files": [
     "id_generator_bg.wasm",
     "id_generator.js",
     "id_generator.d.ts"
   ],
+  "main": "id_generator.js",
+  "types": "id_generator.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ],
   "keywords": [
     "wasm",
-    "webassembly",
-    "rust",
     "id-generator",
     "uuid",
-    "uuid-v4",
-    "uuid-v7",
     "nulid"
-  ],
-  "author": "kakilangit",
-  "license": "MIT",
-  "homepage": "https://dev.kakilangit.com"
-}
+  ]
+}