IdGenerator

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 Added in v4.0.0 Source

Constructors

defaultIdGenerator

Added in v4.0.0 Source

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/unstable/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

Added in v4.0.0 Source

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/unstable/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/unstable/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

Added in v4.0.0 Source

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/unstable/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

Added in v4.0.0 Source

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/unstable/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

Added in v4.0.0 Source

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/unstable/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

Added in v4.0.0 Source

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/unstable/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"