base60-codec 0.1.1

package/README.md

@@ -0,0 +1,128 @@
+# 📦 base60-codec
+
+A tiny, fast, and deterministic Base60 encoder/decoder for TypeScript.
+
+- Fixed-length Base60 IDs for UUID / ULID / Int64
+- BigInt-based (no precision loss)
+- Stable alphabet (0–9 A–Z a–z without ambiguous characters)
+- Brand types for type-safe Base60 strings
+- Zero dependencies
+- ESM ready (NodeNext)
+
+Ideal for generating compact, URL-safe IDs with predictable ordering.
+
+## 🚀 Installation
+
+```
+npm install base60-codec
+```
+
+## 🧩 Quick Usage
+
+```
+import { base60 } from "base60-codec";
+
+const uuid = "550e8400-e29b-41d4-a716-446655440000";
+
+// Encode as 22-char Base60
+const encoded = base60.encodeUUID(uuid);
+console.log(encoded); // e.g. "09EzBRW... (22 chars)"
+
+// Decode back to UUID
+console.log(base60.decodeUUID(encoded));
+// → "550e8400-e29b-41d4-a716-446655440000"
+```
+
+## ✨ Features
+
+### ✅ UUID (128-bit) → 22 chars
+
+```
+encodeUUID(uuid: string): string
+decodeUUID(id: Base60String): string
+```
+
+### ✅ ULID (26 chars Base32) → 22 chars
+
+```
+encodeULID(ulid: string): Base60String
+decodeULID(id: Base60String): string
+```
+
+### ✅ Int64 → 11 chars
+
+```
+encodeInt64(num: number | bigint): string
+decodeInt64(id: Base60String): bigint
+```
+
+### ✅ BigInt encoding
+
+```
+encodeBigInt(value: bigint, padLength?: number): string
+decodeToBigInt(text: Base60String): bigint
+```
+
+### ✅ Safe comparison
+
+```
+compareAsBigInt(a: Base60String, b: Base60String): -1 | 0 | 1
+```
+
+### ✅ Type-safe Base60 string guard
+
+```
+if (base60.isValidBase60(text)) {
+// text is now typed as Base60String
+}
+```
+
+## 📏 Alphabet
+
+```
+0123456789ABCDEFGHIJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
+```
+
+- No visually ambiguous characters (0/O, I/l, etc.)
+- Stable ordering
+- URL-safe
+
+## ⚠️ Notes
+
+1. `encodeBytes()` / `decodeToBytes()` **is not fully reversible**
+
+Leading zero bytes are dropped:
+
+```
+encodeBytes(Uint8Array([0,1,2]))
+↓
+decodeToBytes(...) → [1,2]
+```
+
+This is expected: Base60 → BigInt → bytes produces the minimal byte length.
+
+UUID / ULID / Int64 are unaffected because they use fixed 16-byte / 8-byte decoding internally.
+
+## 🧪 Testing
+
+```
+npm test
+```
+
+Uses Vitest.
+
+## 📜 License
+
+MIT
+
+## 🎉 Summary
+
+base60-codec gives you:
+
+- deterministic, compact, comparable Base60 identifiers
+- 22-char identifiers for both UUID & ULID
+- 11-char identifiers for Int64
+- safe brand-typed Base60 strings
+- pure TypeScript implementation (no deps)
+
+Perfect for generating short IDs in databases, URLs, logs, or distributed systems.

package/dist/index.cjs

@@ -0,0 +1,191 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  base60: () => base60,
+  createBase60Codec: () => createBase60Codec
+});
+module.exports = __toCommonJS(index_exports);
+var FIXED_LEN_UUID = 22;
+var FIXED_LEN_ULID = 22;
+var FIXED_LEN_INT64 = 11;
+var alphabet = "0123456789ABCDEFGHIJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var crockford = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function createBase60Codec() {
+  const base = BigInt(alphabet.length);
+  const charToValue = /* @__PURE__ */ new Map();
+  for (let i = 0; i < alphabet.length; i++) {
+    charToValue.set(alphabet[i], BigInt(i));
+  }
+  function leftPad(text, length) {
+    if (text.length > length) {
+      throw new Error(
+        `Encoded value length (${text.length}) exceeds fixed length ${length}`
+      );
+    }
+    return text.padStart(length, alphabet[0]);
+  }
+  function bytesToBigInt(bytes) {
+    let result = 0n;
+    for (const b of bytes) {
+      result = (result << 8n) + BigInt(b);
+    }
+    return result;
+  }
+  function bigIntToBytes(value, fixedLength) {
+    if (value < 0n) {
+      throw new Error("negative bigint is not supported");
+    }
+    let hex = value.toString(16);
+    if (hex.length % 2 === 1) hex = "0" + hex;
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+    }
+    if (fixedLength !== void 0) {
+      if (bytes.length > fixedLength) {
+        throw new Error("decoded bytes exceed fixed length");
+      }
+      const padded = new Uint8Array(fixedLength);
+      padded.set(bytes, fixedLength - bytes.length);
+      return padded;
+    }
+    return bytes;
+  }
+  function encodeBigInt(value, padLength) {
+    if (value === 0n) {
+      return padLength != null ? leftPad(alphabet[0], padLength) : alphabet[0];
+    }
+    let v = value;
+    let out = "";
+    while (v > 0n) {
+      const mod = v % base;
+      v = v / base;
+      out = alphabet[Number(mod)] + out;
+    }
+    return padLength != null ? leftPad(out, padLength) : out;
+  }
+  function decodeToBigInt(text) {
+    let v = 0n;
+    for (const ch of text) {
+      const d = charToValue.get(ch);
+      if (d === void 0) {
+        throw new Error(`invalid character "${ch}"`);
+      }
+      v = v * base + d;
+    }
+    return v;
+  }
+  return {
+    alphabet,
+    encodeBytes(bytes) {
+      return encodeBigInt(bytesToBigInt(bytes));
+    },
+    decodeToBytes(text) {
+      return bigIntToBytes(decodeToBigInt(text));
+    },
+    encodeBigInt,
+    decodeToBigInt,
+    encodeInt64(value) {
+      return leftPad(
+        encodeBigInt(BigInt(value)),
+        FIXED_LEN_INT64
+      );
+    },
+    decodeInt64(text) {
+      if (text.length !== FIXED_LEN_INT64) {
+        throw new Error(`Expected ${FIXED_LEN_INT64} chars for Base60 Int64`);
+      }
+      return decodeToBigInt(text);
+    },
+    encodeUUID(uuid) {
+      const hex = uuid.replace(/-/g, "");
+      if (hex.length !== 32) throw new Error("invalid UUID");
+      const bytes = new Uint8Array(16);
+      for (let i = 0; i < 16; i++) {
+        bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+      }
+      return leftPad(
+        encodeBigInt(bytesToBigInt(bytes)),
+        FIXED_LEN_UUID
+      );
+    },
+    decodeUUID(text) {
+      const bytes = bigIntToBytes(decodeToBigInt(text), 16);
+      const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+      return hex.slice(0, 8) + "-" + hex.slice(8, 12) + "-" + hex.slice(12, 16) + "-" + hex.slice(16, 20) + "-" + hex.slice(20);
+    },
+    encodeULID(ulid) {
+      if (!/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(ulid)) {
+        throw new Error("Invalid ULID format");
+      }
+      const map32 = /* @__PURE__ */ new Map();
+      for (let i = 0; i < crockford.length; i++) {
+        map32.set(crockford[i], i);
+      }
+      let value = 0n;
+      for (const ch of ulid.toUpperCase()) {
+        const v = map32.get(ch);
+        if (v === void 0) throw new Error(`Invalid ULID char: ${ch}`);
+        value = (value << 5n) + BigInt(v);
+      }
+      const raw = this.encodeBigInt(value);
+      return leftPad(raw, FIXED_LEN_ULID);
+    },
+    decodeULID(text) {
+      if (text.length !== 22) {
+        throw new Error("Expected 22-char Base60 ULID");
+      }
+      const value = this.decodeToBigInt(text);
+      const bytes = bigIntToBytes(value, 16);
+      let bits = "";
+      for (const b of bytes) {
+        bits += b.toString(2).padStart(8, "0");
+      }
+      const padded = bits.padStart(130, "0");
+      let ulid = "";
+      for (let i = 0; i < 26; i++) {
+        const chunk = padded.slice(i * 5, i * 5 + 5);
+        ulid += crockford[parseInt(chunk, 2)];
+      }
+      return ulid;
+    },
+    compareAsBigInt(a, b) {
+      const ai = decodeToBigInt(a);
+      const bi = decodeToBigInt(b);
+      if (ai < bi) return -1;
+      if (ai > bi) return 1;
+      return 0;
+    },
+    isValidBase60: (text) => {
+      for (const ch of text) {
+        if (!alphabet.includes(ch)) return false;
+      }
+      return true;
+    }
+  };
+}
+var base60 = createBase60Codec();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  base60,
+  createBase60Codec
+});

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+type Base60String = string & {
+    __brand_base60: true;
+};
+interface Base60Codec {
+    alphabet: Base60String;
+    encodeBytes(bytes: Uint8Array): string;
+    decodeToBytes(text: Base60String): Uint8Array;
+    encodeBigInt(value: bigint, padLength?: number): Base60String;
+    decodeToBigInt(text: Base60String): bigint;
+    encodeInt64(value: number | bigint): Base60String;
+    decodeInt64(text: Base60String): bigint;
+    encodeUUID(uuid: string): Base60String;
+    decodeUUID(text: Base60String): string;
+    encodeULID(ulid: string): Base60String;
+    decodeULID(text: Base60String): string;
+    compareAsBigInt(a: Base60String, b: Base60String): number;
+    isValidBase60(text: string): text is Base60String;
+}
+declare function createBase60Codec(): Base60Codec;
+declare const base60: Base60Codec;
+
+export { type Base60Codec, type Base60String, base60, createBase60Codec };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+type Base60String = string & {
+    __brand_base60: true;
+};
+interface Base60Codec {
+    alphabet: Base60String;
+    encodeBytes(bytes: Uint8Array): string;
+    decodeToBytes(text: Base60String): Uint8Array;
+    encodeBigInt(value: bigint, padLength?: number): Base60String;
+    decodeToBigInt(text: Base60String): bigint;
+    encodeInt64(value: number | bigint): Base60String;
+    decodeInt64(text: Base60String): bigint;
+    encodeUUID(uuid: string): Base60String;
+    decodeUUID(text: Base60String): string;
+    encodeULID(ulid: string): Base60String;
+    decodeULID(text: Base60String): string;
+    compareAsBigInt(a: Base60String, b: Base60String): number;
+    isValidBase60(text: string): text is Base60String;
+}
+declare function createBase60Codec(): Base60Codec;
+declare const base60: Base60Codec;
+
+export { type Base60Codec, type Base60String, base60, createBase60Codec };

package/dist/index.js

@@ -0,0 +1,165 @@
+// src/index.ts
+var FIXED_LEN_UUID = 22;
+var FIXED_LEN_ULID = 22;
+var FIXED_LEN_INT64 = 11;
+var alphabet = "0123456789ABCDEFGHIJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var crockford = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function createBase60Codec() {
+  const base = BigInt(alphabet.length);
+  const charToValue = /* @__PURE__ */ new Map();
+  for (let i = 0; i < alphabet.length; i++) {
+    charToValue.set(alphabet[i], BigInt(i));
+  }
+  function leftPad(text, length) {
+    if (text.length > length) {
+      throw new Error(
+        `Encoded value length (${text.length}) exceeds fixed length ${length}`
+      );
+    }
+    return text.padStart(length, alphabet[0]);
+  }
+  function bytesToBigInt(bytes) {
+    let result = 0n;
+    for (const b of bytes) {
+      result = (result << 8n) + BigInt(b);
+    }
+    return result;
+  }
+  function bigIntToBytes(value, fixedLength) {
+    if (value < 0n) {
+      throw new Error("negative bigint is not supported");
+    }
+    let hex = value.toString(16);
+    if (hex.length % 2 === 1) hex = "0" + hex;
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+    }
+    if (fixedLength !== void 0) {
+      if (bytes.length > fixedLength) {
+        throw new Error("decoded bytes exceed fixed length");
+      }
+      const padded = new Uint8Array(fixedLength);
+      padded.set(bytes, fixedLength - bytes.length);
+      return padded;
+    }
+    return bytes;
+  }
+  function encodeBigInt(value, padLength) {
+    if (value === 0n) {
+      return padLength != null ? leftPad(alphabet[0], padLength) : alphabet[0];
+    }
+    let v = value;
+    let out = "";
+    while (v > 0n) {
+      const mod = v % base;
+      v = v / base;
+      out = alphabet[Number(mod)] + out;
+    }
+    return padLength != null ? leftPad(out, padLength) : out;
+  }
+  function decodeToBigInt(text) {
+    let v = 0n;
+    for (const ch of text) {
+      const d = charToValue.get(ch);
+      if (d === void 0) {
+        throw new Error(`invalid character "${ch}"`);
+      }
+      v = v * base + d;
+    }
+    return v;
+  }
+  return {
+    alphabet,
+    encodeBytes(bytes) {
+      return encodeBigInt(bytesToBigInt(bytes));
+    },
+    decodeToBytes(text) {
+      return bigIntToBytes(decodeToBigInt(text));
+    },
+    encodeBigInt,
+    decodeToBigInt,
+    encodeInt64(value) {
+      return leftPad(
+        encodeBigInt(BigInt(value)),
+        FIXED_LEN_INT64
+      );
+    },
+    decodeInt64(text) {
+      if (text.length !== FIXED_LEN_INT64) {
+        throw new Error(`Expected ${FIXED_LEN_INT64} chars for Base60 Int64`);
+      }
+      return decodeToBigInt(text);
+    },
+    encodeUUID(uuid) {
+      const hex = uuid.replace(/-/g, "");
+      if (hex.length !== 32) throw new Error("invalid UUID");
+      const bytes = new Uint8Array(16);
+      for (let i = 0; i < 16; i++) {
+        bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+      }
+      return leftPad(
+        encodeBigInt(bytesToBigInt(bytes)),
+        FIXED_LEN_UUID
+      );
+    },
+    decodeUUID(text) {
+      const bytes = bigIntToBytes(decodeToBigInt(text), 16);
+      const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+      return hex.slice(0, 8) + "-" + hex.slice(8, 12) + "-" + hex.slice(12, 16) + "-" + hex.slice(16, 20) + "-" + hex.slice(20);
+    },
+    encodeULID(ulid) {
+      if (!/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(ulid)) {
+        throw new Error("Invalid ULID format");
+      }
+      const map32 = /* @__PURE__ */ new Map();
+      for (let i = 0; i < crockford.length; i++) {
+        map32.set(crockford[i], i);
+      }
+      let value = 0n;
+      for (const ch of ulid.toUpperCase()) {
+        const v = map32.get(ch);
+        if (v === void 0) throw new Error(`Invalid ULID char: ${ch}`);
+        value = (value << 5n) + BigInt(v);
+      }
+      const raw = this.encodeBigInt(value);
+      return leftPad(raw, FIXED_LEN_ULID);
+    },
+    decodeULID(text) {
+      if (text.length !== 22) {
+        throw new Error("Expected 22-char Base60 ULID");
+      }
+      const value = this.decodeToBigInt(text);
+      const bytes = bigIntToBytes(value, 16);
+      let bits = "";
+      for (const b of bytes) {
+        bits += b.toString(2).padStart(8, "0");
+      }
+      const padded = bits.padStart(130, "0");
+      let ulid = "";
+      for (let i = 0; i < 26; i++) {
+        const chunk = padded.slice(i * 5, i * 5 + 5);
+        ulid += crockford[parseInt(chunk, 2)];
+      }
+      return ulid;
+    },
+    compareAsBigInt(a, b) {
+      const ai = decodeToBigInt(a);
+      const bi = decodeToBigInt(b);
+      if (ai < bi) return -1;
+      if (ai > bi) return 1;
+      return 0;
+    },
+    isValidBase60: (text) => {
+      for (const ch of text) {
+        if (!alphabet.includes(ch)) return false;
+      }
+      return true;
+    }
+  };
+}
+var base60 = createBase60Codec();
+export {
+  base60,
+  createBase60Codec
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "base60-codec",
+  "version": "0.1.1",
+  "description": "A tiny, deterministic Base60 encoder/decoder for UUID, ULID, Int64, and BigInt.",
+  "author": "Shinnosuke Hagiwara <hagiwara000@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.7.0",
+    "vitest": "^1.5.0"
+  }
+}