IdGenerator.ts overview

The IdGenerator module provides a pluggable system for generating unique identifiers for tool calls and other items in the Effect AI SDKs.

This module offers a flexible and configurable approach to ID generation, supporting custom alphabets, prefixes, separators, and sizes.

Example

import { IdGenerator } from "@effect/ai"
import { Effect, Layer } from "effect"

// Using the default ID generator
const program = Effect.gen(function* () {
  const idGen = yield* IdGenerator.IdGenerator
  const toolCallId = yield* idGen.generateId()
  console.log(toolCallId) // "id_A7xK9mP2qR5tY8uV"
  return toolCallId
}).pipe(Effect.provide(Layer.succeed(IdGenerator.IdGenerator, IdGenerator.defaultIdGenerator)))

Example

import { IdGenerator } from "@effect/ai"
import { Effect, Layer } from "effect"

// Creating a custom ID generator for AI tool calls
const customLayer = IdGenerator.layer({
  alphabet: "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
  prefix: "tool_call",
  separator: "-",
  size: 12
})

const program = Effect.gen(function* () {
  const idGen = yield* IdGenerator.IdGenerator
  const id = yield* idGen.generateId()
  console.log(id) // "tool_call-A7XK9MP2QR5T"
  return id
}).pipe(Effect.provide(customLayer))

Since v1.0.0

Constructors

defaultIdGenerator

Default ID generator service implementation.

Uses the standard configuration with “id” prefix and generates IDs in the format “id_XXXXXXXXXXXXXXXX” where X represents random alphanumeric characters.

Example

import { IdGenerator } from "@effect/ai"
import { Effect, Layer } from "effect"

const program = Effect.gen(function* () {
  const id = yield* IdGenerator.defaultIdGenerator.generateId()
  console.log(id) // "id_A7xK9mP2qR5tY8uV"
  return id
})

// Or provide it as a service
const withDefault = program.pipe(Effect.provideService(IdGenerator.IdGenerator, IdGenerator.defaultIdGenerator))

Signature

declare const defaultIdGenerator: Service

Source

Since v1.0.0

layer

Creates a Layer that provides the IdGenerator service with custom configuration.

This is the recommended way to provide ID generation capabilities to your application. The layer will fail during construction if the configuration is invalid.

Example

import { IdGenerator } from "@effect/ai"
import { Effect, Layer } from "effect"

// Create a layer for generating AI tool call IDs
const toolCallIdLayer = IdGenerator.layer({
  alphabet: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  prefix: "tool_call",
  separator: "_",
  size: 12
})

const program = Effect.gen(function* () {
  const idGen = yield* IdGenerator.IdGenerator
  const toolCallId = yield* idGen.generateId()
  console.log(toolCallId) // "tool_call_A7XK9MP2QR5T"
  return toolCallId
}).pipe(Effect.provide(toolCallIdLayer))

Signature

declare const layer: (options: MakeOptions) => Layer.Layer<IdGenerator, Cause.IllegalArgumentException>

Source

Since v1.0.0

make

Creates a custom ID generator service with the specified options.

Validates the configuration to ensure the separator is not part of the alphabet, which would cause ambiguity in parsing generated IDs.

Example

import { IdGenerator } from "@effect/ai"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  // Create a generator for AI assistant message IDs
  const messageIdGen = yield* IdGenerator.make({
    alphabet: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    prefix: "msg",
    separator: "-",
    size: 10
  })

  const messageId = yield* messageIdGen.generateId()
  console.log(messageId) // "msg-A7X9K2M5P8"
  return messageId
})

Example

import { IdGenerator } from "@effect/ai"
import { Effect } from "effect"

// This will fail with IllegalArgumentException
const invalidConfig = IdGenerator.make({
  alphabet: "ABC123",
  prefix: "test",
  separator: "A", // Error: separator is part of alphabet
  size: 8
})

const program = Effect.gen(function* () {
  const generator = yield* invalidConfig
  return generator
}).pipe(Effect.catchAll((error) => Effect.succeed(`Configuration error: ${error.message}`)))

Signature

declare const make: (
  args_0: MakeOptions
) => Effect.Effect<
  { readonly generateId: () => Effect.Effect<string, never, never> },
  Cause.IllegalArgumentException,
  never
>

Source

Since v1.0.0

Models

IdGenerator (class)

The IdGenerator service tag for dependency injection.

This tag is used to provide and access ID generation functionality throughout the application. It follows Effect’s standard service pattern for type-safe dependency injection.

Example

import { IdGenerator } from "@effect/ai"
import { Effect } from "effect"

const useIdGenerator = Effect.gen(function* () {
  const idGenerator = yield* IdGenerator.IdGenerator
  const newId = yield* idGenerator.generateId()
  return newId
})

Signature

declare class IdGenerator

Source

Since v1.0.0

MakeOptions (interface)

Configuration options for creating custom ID generators.

Example

import { IdGenerator } from "@effect/ai"

// Configuration for tool call IDs
const toolCallOptions: IdGenerator.MakeOptions = {
  alphabet: "0123456789ABCDEF",
  prefix: "tool",
  separator: "_",
  size: 8
}

// This will generate IDs like: "tool_A1B2C3D4"

Signature

export interface MakeOptions {
  /**
   * The character set to use for generating the random portion of IDs.
   */
  readonly alphabet: string
  /**
   * Optional prefix to prepend to generated IDs.
   */
  readonly prefix?: string | undefined
  /**
   * Character used to separate the prefix from the random portion.
   */
  readonly separator: string
  /**
   * Length of the random portion of the generated ID.
   */
  readonly size: number
}

Source

Since v1.0.0

Service (interface)

The service interface for ID generation.

Defines the contract that all ID generator implementations must fulfill. The service provides a single method for generating unique identifiers in an effectful context.

Example

import { IdGenerator } from "@effect/ai"
import { Effect } from "effect"

// Custom implementation
const customService: IdGenerator.Service = {
  generateId: () => Effect.succeed(`custom_${Date.now()}`)
}

const program = Effect.gen(function* () {
  const id = yield* customService.generateId()
  console.log(id) // "custom_1234567890"
  return id
})

Signature

export interface Service {
  readonly generateId: () => Effect.Effect<string>
}

Source

Since v1.0.0