IdGenerator unstable

Provides identifier generation for AI features.

The IdGenerator service exposes one operation, generateId, which returns a string inside Effect. AI modules use it for values such as tool call ids and generated response item ids. This module includes the service tag, service interface, default generator, configurable custom generator, and layer for providing the service.

6 exports Since v4.0.0 Source

Constructors

defaultIdGenerator

unstable

Since v4.0.0

Default ID generator service implementation.

Details

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

Signature

declare const defaultIdGenerator: Service

Example Generating default IDs

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

const program = Effect.gen(function*() {
  const id = yield* IdGenerator.defaultIdGenerator.generateId()
  return id
})

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

const id = await Effect.runPromise(withDefault)
const result = [id.startsWith("id_"), id.length] // => [true, 19]

make

unstable

Since v4.0.0

Creates a custom ID generator service with the specified options.

Details

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

Signature

declare const make: (...args: [MakeOptions]) => Effect<{
  generateId: (...args: []) => Effect<string, never, never>;
}, IllegalArgumentError, never>

Example Creating a custom generator

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

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
  })

  return yield* messageIdGen.generateId()
})

const messageId = await Effect.runPromise(program)
const result = [messageId.startsWith("msg-"), messageId.length] // => [true, 14]

Example Handling invalid generator options

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

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

const error = await Effect.runPromise(Effect.flip(invalidConfig))
error.message // => 'The separator "A" must not be part of the alphabet "ABC123".'

Layers

layer

unstable

Since v4.0.0

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

When to use

Use when you need to provide ID generation capabilities from validated configuration.

Signature

declare function layer(options: MakeOptions): Layer<IdGenerator, IllegalArgumentError>

Example Providing an ID generator layer

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

// 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
  return yield* idGen.generateId()
}).pipe(Effect.provide(toolCallIdLayer))

const toolCallId = await Effect.runPromise(program)
const result = [toolCallId.startsWith("tool_call_"), toolCallId.length] // => [true, 22]

Models

Service

interface unstable

Since v4.0.0

The service interface for ID generation.

Details

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

Signature

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

Example Implementing a custom ID generator

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

// Custom deterministic implementation
let nextId = 0
const customService: IdGenerator.Service = {
  generateId: () => Effect.sync(() => `custom_${++nextId}`)
}

const program = customService.generateId()

await Effect.runPromise(program) // => "custom_1"

Options

MakeOptions

interface unstable

Since v4.0.0

Configuration options for creating custom ID generators.

Signature

interface MakeOptions {
  readonly alphabet: string;
  readonly prefix?: string;
  readonly separator: string;
  readonly size: number;
}

Example Configuring generated IDs

import type { 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"
const result = [toolCallOptions.prefix, toolCallOptions.size] // => ["tool", 8]

Services

IdGenerator

unstable

Since v4.0.0

Service tag for AI identifier generation services.

When to use

Use to access or provide the service that creates identifiers for AI tool calls and related generated values.

Details

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.

Signature

declare class IdGenerator extends Shape<"@effect/ai/IdGenerator", Service, this> {
  constructor(_: never);
}

Example Accessing the ID generator service

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

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

const program = useIdGenerator.pipe(
  Effect.provideService(IdGenerator.IdGenerator, {
    generateId: () => Effect.succeed("id-1")
  })
)
await Effect.runPromise(program) // => "id-1"