IdGenerator

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

6 exports Added in v1.0.0 Source

Constructors

defaultIdGenerator

Added in v1.0.0 Source

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.

Signature

declare const defaultIdGenerator: Service

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

layer

Added in v1.0.0 Source

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.

Signature

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

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

make

Added in v1.0.0 Source

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.

Signature

declare const make: (...args: [MakeOptions]) => Effect<any, unknown, unknown>

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

Models

IdGenerator

Added in v1.0.0 Source

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.

Signature

declare class IdGenerator extends any {
  constructor();
}

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

MakeOptions interface

Added in v1.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

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"

Service interface

Added in v1.0.0 Source

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.

Signature

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

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