@typed/id 0.11.0 → 0.13.0

package/package.json

@@ -1,66 +1,42 @@
 {
   "name": "@typed/id",
-  "version": "0.11.0",
-  "description": "",
+  "version": "0.13.0",
+  "description": "Common ID format generation for Effect",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "keywords": [
+    "effect",
+    "ID",
+    "UUID",
+    "NanoId",
+    "ULID",
+    "typescript"
+  ],
+  "author": "Tylor Steinberger <tlsteinberger167@gmail.com>",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tylors/typed.git"
-  },
-  "sideEffects": [],
-  "author": "Typed contributors",
-  "homepage": "https://github.com/tylors/typed",
   "dependencies": {
-    "@effect/schema": "^0.74.1",
-    "effect": "^3.8.4",
-    "fast-check": "^3.22.0",
-    "@typed/context": "0.30.0"
+    "effect": "^3.11.9"
+  },
+  "peerDependencies": {
+    "effect": "^3.11.9"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@effect/vitest": "^0.16.0",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.4.2",
+    "vitest": "^2.1.8"
   },
-  "main": "./dist/cjs/index.js",
-  "module": "./dist/esm/index.js",
-  "types": "./dist/dts/index.d.ts",
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "types": "./dist/dts/index.d.ts",
-      "import": "./dist/esm/index.js",
-      "default": "./dist/cjs/index.js"
-    },
-    "./GetRandomValues": {
-      "types": "./dist/dts/GetRandomValues.d.ts",
-      "import": "./dist/esm/GetRandomValues.js",
-      "default": "./dist/cjs/GetRandomValues.js"
-    },
-    "./NanoId": {
-      "types": "./dist/dts/NanoId.d.ts",
-      "import": "./dist/esm/NanoId.js",
-      "default": "./dist/cjs/NanoId.js"
-    },
-    "./Schema": {
-      "types": "./dist/dts/Schema.d.ts",
-      "import": "./dist/esm/Schema.js",
-      "default": "./dist/cjs/Schema.js"
-    },
-    "./Uuid": {
-      "types": "./dist/dts/Uuid.d.ts",
-      "import": "./dist/esm/Uuid.js",
-      "default": "./dist/cjs/Uuid.js"
-    }
+  "publishConfig": {
+    "access": "public"
   },
-  "typesVersions": {
-    "*": {
-      "GetRandomValues": [
-        "./dist/dts/GetRandomValues.d.ts"
-      ],
-      "NanoId": [
-        "./dist/dts/NanoId.d.ts"
-      ],
-      "Schema": [
-        "./dist/dts/Schema.d.ts"
-      ],
-      "Uuid": [
-        "./dist/dts/Uuid.d.ts"
-      ]
-    }
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "biome lint --write",
+    "test:watch": "vitest --typecheck",
+    "test": "vitest run --typecheck",
+    "typecheck": "tsc --noEmit"
   }
 }

package/readme.md

@@ -0,0 +1,86 @@
+# @typed/id
+
+A TypeScript library providing common ID format generation using [Effect](https://effect.website/). This package includes implementations for UUID, NanoID, and ULID generation with a focus on type safety and functional programming principles.
+
+## Installation
+
+```bash
+npm install @typed/id effect
+# or
+pnpm add @typed/id effect
+# or
+yarn add @typed/id effect
+```
+
+## Features
+
+- 🎯 Type-safe ID generation
+- 🔧 Built on top of Effect
+- 🎨 Multiple ID format support:
+  - UUID (v4)
+  - NanoID
+  - ULID
+- ⚡ Efficient and secure random value generation
+- 📦 Zero dependencies (except Effect)
+
+## Usage
+
+```typescript
+import { Effect } from 'effect'
+import { 
+  DateTimes, 
+  GetRandomValues, 
+  makeUuid, 
+  makeNanoId, 
+  makeUlid 
+} from '@typed/id'
+
+// Generate a UUID
+await makeUuid.pipe(
+  Effect.provide(GetRandomValues.CryptoRandom),
+  // Effect.provide(GetRandomValues.PseudoRandom),
+  Effect.flatMap(Effect.log),
+  Effect.runPromise
+)
+// Output: "550e8400-e29b-41d4-a716-446655440000"
+
+// Generate a NanoID
+await makeNanoId.pipe(
+  Effect.provide(GetRandomValues.CryptoRandom),
+  // Effect.provide(GetRandomValues.PseudoRandom),
+  Effect.flatMap(Effect.log),
+  Effect.runPromise
+)
+// Output: "V1StGXR8_Z5jdHi6B-myT"
+
+// Generate a ULID
+await makeUlid.pipe(
+  Effect.provide([
+    GetRandomValues.CryptoRandom, 
+    // GetRandomValues.PseudoRandom,
+    DateTimes.Default
+    // DateTimes.Fixed(new Date(0))
+  ]),
+  Effect.flatMap(Effect.log),
+  Effect.runPromise
+)
+// Output: "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+```
+
+## API
+
+### UUID
+
+- `makeUuid`: Generates a v4 UUID
+
+### NanoID
+
+- `makeNanoId`: Generates a NanoID with a default length of 21 characters
+
+### ULID
+
+- `makeUlid`: Generates a ULID (Universally Unique Lexicographically Sortable Identifier)
+
+## License
+
+MIT

package/src/DateTimes.ts

@@ -0,0 +1,37 @@
+import { Effect, Layer, Option, TestClock } from 'effect'
+
+export class DateTimes extends Effect.Tag('DateTimes')<
+  DateTimes,
+  {
+    readonly now: Effect.Effect<number>
+    readonly date: Effect.Effect<Date>
+  }
+>() {
+  static readonly make = (now: Effect.Effect<number>): Layer.Layer<DateTimes> =>
+    Layer.succeed(this, {
+      now,
+      date: now.pipe(Effect.map((millis) => new Date(millis))),
+    })
+
+  static readonly Default: Layer.Layer<DateTimes> = this.make(Effect.clockWith((clock) => clock.currentTimeMillis))
+
+  static readonly Fixed = (base: Date): Layer.Layer<DateTimes> =>
+    Layer.effect(
+      DateTimes,
+      Effect.gen(function* () {
+        const clock = yield* Effect.clock
+        const startMillis = yield* clock.currentTimeMillis
+        const now = clock.currentTimeMillis.pipe(
+          Effect.map((millis) =>
+            // Use BigInt to avoid floating point precision issues which can break deterministic testing
+            Number(BigInt(base.getTime()) + BigInt(millis) - BigInt(startMillis)),
+          ),
+        )
+
+        return {
+          now,
+          date: now.pipe(Effect.map((millis) => new Date(millis))),
+        }
+      }),
+    )
+}

package/src/GetRandomValues.ts

@@ -1,78 +1,29 @@
-/**
- * @since 1.0.0
- */
-
-import * as Context from "@typed/context"
-import * as Effect from "effect/Effect"
-import type * as Layer from "effect/Layer"
-import * as Random from "effect/Random"
-
-/**
- * @since 1.0.0
- */
-export const GetRandomValues = Context.Fn<(length: number) => Effect.Effect<Uint8Array>>()(
-  (_) => (class GetRandomValues extends _("@typed/id/GetRandomValues") {})
-)
-/**
- * @since 1.0.0
- */
-export interface GetRandomValues extends Context.Fn.Identifier<typeof GetRandomValues> {}
-
-const getRandomValuesWeb = (crypto: Crypto, length: number) => crypto.getRandomValues(new Uint8Array(length))
-
-/**
- * @since 1.0.0
- */
-export const webCrypto = (crypto: Crypto): Layer.Layer<GetRandomValues> =>
-  GetRandomValues.implement((length) => Effect.sync(() => getRandomValuesWeb(crypto, length)))
-
-/**
- * @since 1.0.0
- */
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
-export const getRandomValuesNode = (crypto: typeof import("node:crypto"), length: number) => {
-  const bytes = crypto.randomBytes(length)
-  const view = new Uint8Array(length)
-  for (let i = 0; i < bytes.length; ++i) {
-    view[i] = bytes[i]
-  }
-  return view
+import * as Context from 'effect/Context'
+import * as Effect from 'effect/Effect'
+import * as Layer from 'effect/Layer'
+import * as Random from 'effect/Random'
+
+export class GetRandomValues extends Context.Tag('GetRandomValues')<
+  GetRandomValues,
+  (length: number) => Effect.Effect<Uint8Array>
+>() {
+  static readonly layer = (f: (length: number) => Effect.Effect<Uint8Array>) =>
+    Layer.succeed(GetRandomValues, f)
+
+  static readonly apply = (length: number) => Effect.flatMap(GetRandomValues, (f) => f(length))
+
+  static readonly PseudoRandom = this.layer((length) =>
+    Effect.gen(function* () {
+      const view = new Uint8Array(length)
+      for (let i = 0; i < length; ++i) {
+        view[i] = yield* Random.nextInt
+      }
+
+      return view
+    }),
+  )
+
+  static readonly CryptoRandom = this.layer((length) =>
+    Effect.sync(() => crypto.getRandomValues(new Uint8Array(length))),
+  )
 }
-
-/**
- * @since 1.0.0
- */
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
-export const nodeCrypto = (crypto: typeof import("node:crypto")): Layer.Layer<GetRandomValues> =>
-  GetRandomValues.implement((length) => Effect.sync(() => getRandomValuesNode(crypto, length)))
-
-/**
- * @since 1.0.0
- */
-export const pseudoRandom: Layer.Layer<GetRandomValues> = GetRandomValues.implement((length) =>
-  Effect.gen(function*() {
-    const view = new Uint8Array(length)
-
-    for (let i = 0; i < length; ++i) {
-      view[i] = yield* Random.nextInt
-    }
-
-    return view
-  })
-)
-
-/**
- * @since 1.0.0
- */
-export const getRandomValues: Layer.Layer<GetRandomValues> = GetRandomValues.layer(
-  Effect.gen(function*() {
-    if (typeof crypto === "undefined") {
-      // eslint-disable-next-line @typescript-eslint/consistent-type-imports
-      const crypto: typeof import("node:crypto") = yield* Effect.promise(() => import("node:crypto"))
-
-      return (length: number) => Effect.sync(() => getRandomValuesNode(crypto, length))
-    } else {
-      return (length: number) => Effect.sync(() => getRandomValuesWeb(crypto, length))
-    }
-  })
-)

package/src/NanoId.ts

@@ -1,34 +1,14 @@
-/**
- * @since 1.0.0
- */
-
-import * as Brand from "effect/Brand"
-import * as Effect from "effect/Effect"
-import { GetRandomValues } from "./GetRandomValues.js"
+import { Schema } from 'effect'
+import * as Effect from 'effect/Effect'
+import { GetRandomValues } from './GetRandomValues.js'
 
 const nanoIdPattern = /[0-9a-zA-Z_-]/
 
-/**
- * @since 1.0.0
- */
 export const isNanoId = (id: string): id is NanoId => nanoIdPattern.test(id)
 
-/**
- * @since 1.0.0
- */
-export type NanoId = string & Brand.Brand<"@typed/id/NanoId">
-
-/**
- * @since 1.0.0
- */
-export const NanoId = Brand.refined<NanoId>(
-  isNanoId,
-  (input) => Brand.error(`Expected a NanoID but received ${input}.`)
-)
+export const NanoId = Schema.String.pipe(Schema.brand('@typed/id/NanoId'))
+export type NanoId = Schema.Schema.Type<typeof NanoId>
 
-/**
- * @since 1.0.0
- */
 export type NanoIdSeed = readonly [
   zero: number,
   one: number,
@@ -50,7 +30,7 @@ export type NanoIdSeed = readonly [
   seventeen: number,
   eighteen: number,
   nineteen: number,
-  twenty: number
+  twenty: number,
 ]
 
 const numToCharacter = (byte: number): string => {
@@ -62,23 +42,19 @@ const numToCharacter = (byte: number): string => {
     // `A-Z`
     return (byte - 26).toString(36).toUpperCase()
   } else if (byte > 62) {
-    return "-"
+    return '-'
   } else {
-    return "_"
+    return '_'
   }
 }
 
-/**
- * @since 1.0.0
- */
-export const nanoId = (seed: NanoIdSeed): NanoId => NanoId(seed.reduce((id, x) => id + numToCharacter(x), ""))
+export const nanoId = (seed: NanoIdSeed): NanoId =>
+  NanoId.make(seed.reduce((id, x) => id + numToCharacter(x), ''))
 
-/**
- * @since 1.0.0
- */
-export const makeNanoIdSeed: Effect.Effect<NanoIdSeed, never, GetRandomValues> = GetRandomValues(21) as any
+export const makeNanoIdSeed: Effect.Effect<NanoIdSeed, never, GetRandomValues> =
+  GetRandomValues.apply(21) as any
 
-/**
- * @since 1.0.0
- */
-export const makeNanoId: Effect.Effect<NanoId, never, GetRandomValues> = Effect.map(makeNanoIdSeed, nanoId)
+export const makeNanoId: Effect.Effect<NanoId, never, GetRandomValues> = Effect.map(
+  makeNanoIdSeed,
+  nanoId,
+)

package/src/Ulid.ts

@@ -0,0 +1,82 @@
+import * as Effect from 'effect/Effect'
+import { GetRandomValues } from './GetRandomValues.js'
+import { Schema } from 'effect'
+import { DateTimes } from './DateTimes.js'
+
+export const isUlid: (value: string) => value is Ulid = Schema.is(Schema.ULID) as any
+
+export const Ulid = Schema.ULID.pipe(Schema.brand('@typed/id/ULID'))
+export type Ulid = Schema.Schema.Type<typeof Ulid>
+
+export type UlidSeed = {
+  readonly seed: readonly [
+    zero: number,
+    one: number,
+    two: number,
+    three: number,
+    four: number,
+    five: number,
+    six: number,
+    seven: number,
+    eight: number,
+    nine: number,
+    ten: number,
+    eleven: number,
+    twelve: number,
+    thirteen: number,
+    fourteen: number,
+    fifteen: number,
+  ]
+  readonly now: number
+}
+
+// Crockford's Base32
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+const ENCODING_LEN = ENCODING.length
+const TIME_MAX = 2 ** 48 - 1
+const TIME_LEN = 10
+const RANDOM_LEN = 16
+
+export const makeUlidSeed: Effect.Effect<UlidSeed, never, GetRandomValues | DateTimes> =
+  DateTimes.now.pipe(
+    Effect.bindTo('now'),
+    Effect.bind(
+      'seed',
+      () =>
+        GetRandomValues.apply(16) as any as Effect.Effect<UlidSeed['seed'], never, GetRandomValues>,
+    ),
+  )
+
+export const makeUlid: Effect.Effect<Ulid, never, GetRandomValues | DateTimes> = Effect.map(
+  makeUlidSeed,
+  ({ seed, now }) => ulid(seed, now),
+)
+
+function encodeTime(now: number, len: number): string {
+  let str = ''
+  for (let i = len - 1; i >= 0; i--) {
+    const mod = now % ENCODING_LEN
+    str = ENCODING.charAt(mod) + str
+    now = (now - mod) / ENCODING_LEN
+  }
+  return str
+}
+
+function encodeRandom(seed: UlidSeed['seed']): string {
+  let str = ''
+  for (let i = 0; i < RANDOM_LEN; i++) {
+    str = str + ENCODING.charAt(seed[i] % ENCODING_LEN)
+  }
+  return str
+}
+
+export function ulid(seed: UlidSeed['seed'], now: UlidSeed['now']): Ulid {
+  if (now > TIME_MAX) {
+    throw new Error('Cannot generate ULID due to timestamp overflow')
+  }
+
+  const time = encodeTime(now, TIME_LEN)
+  const random = encodeRandom(seed)
+
+  return Ulid.make(time + random)
+}

package/src/Uuid4.ts

@@ -0,0 +1,22 @@
+import * as Effect from 'effect/Effect'
+import { GetRandomValues } from './GetRandomValues.js'
+import { Schema } from 'effect'
+import { uuidStringify } from './UuidStringify.js'
+
+export const Uuid4 = Schema.UUID.pipe(Schema.brand('@typed/id/UUID4'))
+export type Uuid4 = Schema.Schema.Type<typeof Uuid4>
+
+export const isUuid4: (value: string) => value is Uuid4 = Schema.is(Uuid4)
+
+export const makeUuid4: Effect.Effect<Uuid4, never, GetRandomValues> = Effect.map(
+  GetRandomValues.apply(16),
+  uuid4FromSeed,
+)
+
+function uuid4FromSeed(seed: Uint8Array): Uuid4 {
+  // Per 4.4, set bits for version and `clock_seq_hi_and_reserved`
+  seed[6] = (seed[6] & 0x0f) | 0x40
+  seed[8] = (seed[8] & 0x3f) | 0x80
+
+  return uuidStringify(seed) as Uuid4
+}

package/src/Uuid7.ts

@@ -0,0 +1,104 @@
+import * as Effect from 'effect/Effect'
+import { GetRandomValues } from './GetRandomValues.js'
+import { Layer, Schema } from 'effect'
+import { DateTimes } from './DateTimes.js'
+import { uuidStringify } from './UuidStringify.js'
+
+export const Uuid7 = Schema.UUID.pipe(Schema.brand('@typed/id/UUID7'))
+export type Uuid7 = Schema.Schema.Type<typeof Uuid7>
+
+export const isUuid7: (value: string) => value is Uuid7 = Schema.is(Uuid7)
+
+export type Uuid7Seed = {
+  readonly timestamp: number
+  readonly seq: number
+  readonly randomBytes: Uint8Array
+}
+
+export class Uuid7State extends Effect.Tag('Uuid7State')<
+  Uuid7State,
+  {
+    readonly next: Effect.Effect<Uuid7Seed>
+  }
+>() {
+  static Default: Layer.Layer<Uuid7State, never, GetRandomValues | DateTimes> = Layer.effect(
+    this,
+    Effect.gen(function* () {
+      const { now } = yield* DateTimes
+      const getRandomValues = yield* GetRandomValues
+
+      const state = {
+        msecs: Number.NEGATIVE_INFINITY,
+        seq: 0,
+      }
+
+      function updateV7State(now: number, randomBytes: Uint8Array) {
+        if (now > state.msecs) {
+          // Time has moved on! Pick a new random sequence number
+          state.seq =
+            (randomBytes[6] << 23) | (randomBytes[7] << 16) | (randomBytes[8] << 8) | randomBytes[9]
+          state.msecs = now
+        } else {
+          // Bump sequence counter w/ 32-bit rollover
+          state.seq = (state.seq + 1) | 0
+
+          // In case of rollover, bump timestamp to preserve monotonicity. This is
+          // allowed by the RFC and should self-correct as the system clock catches
+          // up. See https://www.rfc-editor.org/rfc/rfc9562.html#section-6.2-9.4
+          if (state.seq === 0) {
+            state.msecs++
+          }
+        }
+      }
+
+      return {
+        next: Effect.gen(function* () {
+          const randomBytes = yield* getRandomValues(16)
+          updateV7State(yield* now, randomBytes)
+          return { timestamp: state.msecs, seq: state.seq, randomBytes }
+        }),
+      }
+    }),
+  )
+}
+
+export const makeUuid7: Effect.Effect<Uuid7, never, Uuid7State> = Effect.map(
+  Uuid7State.next,
+  uuid7FromSeed,
+)
+
+function uuid7FromSeed({ timestamp, seq, randomBytes }: Uuid7Seed): Uuid7 {
+  const result = new Uint8Array(16)
+
+  // byte 0-5: timestamp (48 bits)
+  result[0] = (timestamp / 0x10000000000) & 0xff
+  result[1] = (timestamp / 0x100000000) & 0xff
+  result[2] = (timestamp / 0x1000000) & 0xff
+  result[3] = (timestamp / 0x10000) & 0xff
+  result[4] = (timestamp / 0x100) & 0xff
+  result[5] = timestamp & 0xff
+
+  // byte 6: `version` (4 bits) | sequence bits 28-31 (4 bits)
+  result[6] = 0x70 | ((seq >>> 28) & 0x0f)
+
+  // byte 7: sequence bits 20-27 (8 bits)
+  result[7] = (seq >>> 20) & 0xff
+
+  // byte 8: `variant` (2 bits) | sequence bits 14-19 (6 bits)
+  result[8] = 0x80 | ((seq >>> 14) & 0x3f)
+
+  // byte 9: sequence bits 6-13 (8 bits)
+  result[9] = (seq >>> 6) & 0xff
+
+  // byte 10: sequence bits 0-5 (6 bits) | random (2 bits)
+  result[10] = ((seq << 2) & 0xff) | (randomBytes[10] & 0x03)
+
+  // bytes 11-15: random (40 bits)
+  result[11] = randomBytes[11]
+  result[12] = randomBytes[12]
+  result[13] = randomBytes[13]
+  result[14] = randomBytes[14]
+  result[15] = randomBytes[15]
+
+  return uuidStringify(result) as Uuid7
+}

package/src/UuidStringify.ts

@@ -0,0 +1,31 @@
+const byteToHex: Array<string> = []
+
+for (let i = 0; i < 256; ++i) {
+  byteToHex.push((i + 0x100).toString(16).slice(1))
+}
+
+export function uuidStringify(seed: Uint8Array): string {
+  return (
+    // biome-ignore lint/style/useTemplate: Faster than template literals
+    byteToHex[seed[0]] +
+    byteToHex[seed[1]] +
+    byteToHex[seed[2]] +
+    byteToHex[seed[3]] +
+    '-' +
+    byteToHex[seed[4]] +
+    byteToHex[seed[5]] +
+    '-' +
+    byteToHex[seed[6]] +
+    byteToHex[seed[7]] +
+    '-' +
+    byteToHex[seed[8]] +
+    byteToHex[seed[9]] +
+    '-' +
+    byteToHex[seed[10]] +
+    byteToHex[seed[11]] +
+    byteToHex[seed[12]] +
+    byteToHex[seed[13]] +
+    byteToHex[seed[14]] +
+    byteToHex[seed[15]]
+  )
+}