@effect/ai 0.26.0 → 0.27.0

package/dist/esm/IdGenerator.js

@@ -0,0 +1,245 @@
+/**
+ * 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
+ * ```ts
+ * 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
+ * ```ts
+ * 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 1.0.0
+ */
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Predicate from "effect/Predicate";
+import * as Random from "effect/Random";
+/**
+ * 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
+ * ```ts
+ * 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
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class IdGenerator extends /*#__PURE__*/Context.Tag("@effect/ai/IdGenerator")() {}
+const DEFAULT_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const DEFAULT_SEPARATOR = "_";
+const DEFAULT_SIZE = 16;
+const makeGenerator = ({
+  alphabet = DEFAULT_ALPHABET,
+  prefix,
+  separator = DEFAULT_SEPARATOR,
+  size = DEFAULT_SIZE
+}) => {
+  const alphabetLength = alphabet.length;
+  return Effect.fnUntraced(function* () {
+    const chars = new Array(size);
+    for (let i = 0; i < size; i++) {
+      chars[i] = alphabet[(yield* Random.next) * alphabetLength | 0];
+    }
+    const identifier = chars.join("");
+    if (Predicate.isUndefined(prefix)) {
+      return identifier;
+    }
+    return `${prefix}${separator}${identifier}`;
+  });
+};
+/**
+ * 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
+ * ```ts
+ * 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
+ *   )
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const defaultIdGenerator = {
+  generateId: /*#__PURE__*/makeGenerator({
+    prefix: "id"
+  })
+};
+/**
+ * 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
+ * ```ts
+ * 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
+ * ```ts
+ * 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}`)
+ *   )
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const make = /*#__PURE__*/Effect.fnUntraced(function* ({
+  alphabet = DEFAULT_ALPHABET,
+  prefix,
+  separator = DEFAULT_SEPARATOR,
+  size = DEFAULT_SIZE
+}) {
+  if (alphabet.includes(separator)) {
+    const message = `The separator "${separator}" must not be part of the alphabet "${alphabet}".`;
+    return yield* new Cause.IllegalArgumentException(message);
+  }
+  const generateId = makeGenerator({
+    alphabet,
+    prefix,
+    separator,
+    size
+  });
+  return {
+    generateId
+  };
+});
+/**
+ * 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
+ * ```ts
+ * 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)
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const layer = options => Layer.effect(IdGenerator, make(options));
+//# sourceMappingURL=IdGenerator.js.map

package/dist/esm/IdGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdGenerator.js","names":["Cause","Context","Effect","Layer","Predicate","Random","IdGenerator","Tag","DEFAULT_ALPHABET","DEFAULT_SEPARATOR","DEFAULT_SIZE","makeGenerator","alphabet","prefix","separator","size","alphabetLength","length","fnUntraced","chars","Array","i","next","identifier","join","isUndefined","defaultIdGenerator","generateId","make","includes","message","IllegalArgumentException","layer","options","effect"],"sources":["../../src/IdGenerator.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,OAAO,KAAKA,KAAK,MAAM,cAAc;AACrC,OAAO,KAAKC,OAAO,MAAM,gBAAgB;AACzC,OAAO,KAAKC,MAAM,MAAM,eAAe;AACvC,OAAO,KAAKC,KAAK,MAAM,cAAc;AACrC,OAAO,KAAKC,SAAS,MAAM,kBAAkB;AAC7C,OAAO,KAAKC,MAAM,MAAM,eAAe;AAEvC;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAM,MAAOC,WAAY,sBAAQL,OAAO,CAACM,GAAG,CAAC,wBAAwB,CAAC,EAGnE;AAyEH,MAAMC,gBAAgB,GAAG,gEAAgE;AACzF,MAAMC,iBAAiB,GAAG,GAAG;AAC7B,MAAMC,YAAY,GAAG,EAAE;AAEvB,MAAMC,aAAa,GAAGA,CAAC;EACrBC,QAAQ,GAAGJ,gBAAgB;EAC3BK,MAAM;EACNC,SAAS,GAAGL,iBAAiB;EAC7BM,IAAI,GAAGL;AAAY,CACE,KAAI;EACzB,MAAMM,cAAc,GAAGJ,QAAQ,CAACK,MAAM;EACtC,OAAOf,MAAM,CAACgB,UAAU,CAAC,aAAS;IAChC,MAAMC,KAAK,GAAG,IAAIC,KAAK,CAACL,IAAI,CAAC;IAC7B,KAAK,IAAIM,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGN,IAAI,EAAEM,CAAC,EAAE,EAAE;MAC7BF,KAAK,CAACE,CAAC,CAAC,GAAGT,QAAQ,CAAE,CAAC,OAAOP,MAAM,CAACiB,IAAI,IAAIN,cAAc,GAAI,CAAC,CAAC;IAClE;IACA,MAAMO,UAAU,GAAGJ,KAAK,CAACK,IAAI,CAAC,EAAE,CAAC;IACjC,IAAIpB,SAAS,CAACqB,WAAW,CAACZ,MAAM,CAAC,EAAE;MACjC,OAAOU,UAAU;IACnB;IACA,OAAO,GAAGV,MAAM,GAAGC,SAAS,GAAGS,UAAU,EAAE;EAC7C,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,OAAO,MAAMG,kBAAkB,GAAY;EACzCC,UAAU,eAAEhB,aAAa,CAAC;IAAEE,MAAM,EAAE;EAAI,CAAE;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,OAAO,MAAMe,IAAI,gBAAG1B,MAAM,CAACgB,UAAU,CAAC,WAAU;EAC9CN,QAAQ,GAAGJ,gBAAgB;EAC3BK,MAAM;EACNC,SAAS,GAAGL,iBAAiB;EAC7BM,IAAI,GAAGL;AAAY,CACP;EACZ,IAAIE,QAAQ,CAACiB,QAAQ,CAACf,SAAS,CAAC,EAAE;IAChC,MAAMgB,OAAO,GAAG,kBAAkBhB,SAAS,uCAAuCF,QAAQ,IAAI;IAC9F,OAAO,OAAO,IAAIZ,KAAK,CAAC+B,wBAAwB,CAACD,OAAO,CAAC;EAC3D;EAEA,MAAMH,UAAU,GAAGhB,aAAa,CAAC;IAAEC,QAAQ;IAAEC,MAAM;IAAEC,SAAS;IAAEC;EAAI,CAAE,CAAC;EAEvE,OAAO;IACLY;GACQ;AACZ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,OAAO,MAAMK,KAAK,GAAIC,OAAoB,IACxC9B,KAAK,CAAC+B,MAAM,CAAC5B,WAAW,EAAEsB,IAAI,CAACK,OAAO,CAAC,CAAC","ignoreList":[]}