@funkai/prompts 0.3.0 → 0.4.1

package/src/group.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { createPromptGroup } from "@/group.js";
+import { createPrompt } from "@/prompt.js";
+
+describe(createPromptGroup, () => {
+  it("should set the group on each prompt module", () => {
+    const greeting = createPrompt({
+      name: "greeting",
+      template: "Hello {{ name }}!",
+      schema: z.object({ name: z.string() }),
+    });
+
+    const group = createPromptGroup("agents", { greeting });
+
+    expect(group.greeting.group).toBe("agents");
+  });
+
+  it("should override existing group on prompt modules", () => {
+    const greeting = createPrompt({
+      name: "greeting",
+      group: "old-group",
+      template: "Hello {{ name }}!",
+      schema: z.object({ name: z.string() }),
+    });
+
+    const group = createPromptGroup("agents", { greeting });
+
+    expect(group.greeting.group).toBe("agents");
+  });
+
+  it("should not mutate the original prompt module", () => {
+    const greeting = createPrompt({
+      name: "greeting",
+      template: "Hello {{ name }}!",
+      schema: z.object({ name: z.string() }),
+    });
+
+    createPromptGroup("agents", { greeting });
+
+    expect(greeting.group).toBeUndefined();
+  });
+
+  it("should preserve render functionality", () => {
+    const greeting = createPrompt({
+      name: "greeting",
+      template: "Hello {{ name }}!",
+      schema: z.object({ name: z.string() }),
+    });
+
+    const group = createPromptGroup("agents", { greeting });
+
+    expect(group.greeting.render({ name: "Alice" })).toBe("Hello Alice!");
+  });
+
+  it("should support multiple prompts in a group", () => {
+    const greeting = createPrompt({
+      name: "greeting",
+      template: "Hello {{ name }}!",
+      schema: z.object({ name: z.string() }),
+    });
+
+    const farewell = createPrompt({
+      name: "farewell",
+      template: "Goodbye {{ name }}!",
+      schema: z.object({ name: z.string() }),
+    });
+
+    const group = createPromptGroup("agents", { greeting, farewell });
+
+    expect(group.greeting.group).toBe("agents");
+    expect(group.farewell.group).toBe("agents");
+    expect(group.greeting.render({ name: "Alice" })).toBe("Hello Alice!");
+    expect(group.farewell.render({ name: "Bob" })).toBe("Goodbye Bob!");
+  });
+
+  it("should support nested group paths", () => {
+    const system = createPrompt({
+      name: "system",
+      template: "You are a {{ role }}.",
+      schema: z.object({ role: z.string() }),
+    });
+
+    const group = createPromptGroup("agents/core", { system });
+
+    expect(group.system.group).toBe("agents/core");
+  });
+});

package/src/group.ts

@@ -0,0 +1,36 @@
+import type { PromptModule } from "./types.js";
+
+/**
+ * Create a prompt group namespace from a record of prompt modules.
+ *
+ * Sets the `group` field on each module to the given group name,
+ * producing a new namespace object without mutating the originals.
+ *
+ * @param name - Group name applied to each prompt (e.g. `'agents'`, `'agents/core'`).
+ * @param prompts - Record of prompt modules to group.
+ * @returns A new {@link PromptNamespace} with group-tagged prompt modules.
+ *
+ * @example
+ * ```ts
+ * import { createPrompt, createPromptGroup } from '@funkai/prompts'
+ * import { z } from 'zod'
+ *
+ * const agents = createPromptGroup('agents', {
+ *   greeting: createPrompt({
+ *     name: 'greeting',
+ *     template: 'Hello {{ name }}!',
+ *     schema: z.object({ name: z.string() }),
+ *   }),
+ * })
+ *
+ * agents.greeting.render({ name: 'Alice' })
+ * ```
+ */
+export function createPromptGroup<T extends Record<string, PromptModule>>(
+  name: string,
+  prompts: T,
+): T {
+  return Object.fromEntries(
+    Object.entries(prompts).map(([key, module]) => [key, { ...module, group: name }]),
+  ) as T;
+}

package/src/index.ts

@@ -1,2 +1,4 @@
+export { createPromptGroup } from "./group.js";
+export { createPrompt } from "./prompt.js";
 export { createPromptRegistry } from "./registry.js";
-export type { PromptModule, PromptNamespace, PromptRegistry } from "./types.js";
+export type { PromptConfig, PromptModule, PromptNamespace, PromptRegistry } from "./types.js";

package/src/prompt.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { createPrompt } from "@/prompt.js";
+
+describe(createPrompt, () => {
+  it("should create a prompt module with name and group", () => {
+    const prompt = createPrompt({
+      name: "greeting",
+      group: "agents",
+      template: "Hello {{ name }}!",
+      schema: z.object({ name: z.string() }),
+    });
+
+    expect(prompt.name).toBe("greeting");
+    expect(prompt.group).toBe("agents");
+  });
+
+  it("should set group to undefined when not provided", () => {
+    const prompt = createPrompt({
+      name: "greeting",
+      template: "Hello!",
+      schema: z.object({}),
+    });
+
+    expect(prompt.group).toBeUndefined();
+  });
+
+  it("should render a template with variables", () => {
+    const prompt = createPrompt({
+      name: "greeting",
+      template: "Hello {{ name }}, welcome to {{ place }}!",
+      schema: z.object({ name: z.string(), place: z.string() }),
+    });
+
+    const result = prompt.render({ name: "Alice", place: "Wonderland" });
+    expect(result).toBe("Hello Alice, welcome to Wonderland!");
+  });
+
+  it("should render a static template with no variables", () => {
+    const prompt = createPrompt({
+      name: "static",
+      template: "No variables here.",
+      schema: z.object({}),
+    });
+
+    expect(prompt.render({})).toBe("No variables here.");
+  });
+
+  it("should validate variables against the schema", () => {
+    const prompt = createPrompt({
+      name: "greeting",
+      template: "Hello {{ name }}!",
+      schema: z.object({ name: z.string() }),
+    });
+
+    expect(prompt.validate({ name: "Alice" })).toEqual({ name: "Alice" });
+  });
+
+  it("should throw on invalid variables during render", () => {
+    const prompt = createPrompt({
+      name: "greeting",
+      template: "Hello {{ name }}!",
+      schema: z.object({ name: z.string() }),
+    });
+
+    expect(() => prompt.render({ name: 42 } as never)).toThrow();
+  });
+
+  it("should throw on invalid variables during validate", () => {
+    const prompt = createPrompt({
+      name: "greeting",
+      template: "Hello {{ name }}!",
+      schema: z.object({ name: z.string() }),
+    });
+
+    expect(() => prompt.validate({ name: 42 })).toThrow();
+  });
+
+  it("should expose the schema for external validation", () => {
+    const schema = z.object({ name: z.string() });
+    const prompt = createPrompt({
+      name: "greeting",
+      template: "Hello {{ name }}!",
+      schema,
+    });
+
+    expect(prompt.schema).toBe(schema);
+  });
+});

package/src/prompt.ts

@@ -0,0 +1,60 @@
+import { liquidEngine } from "./engine.js";
+import type { PromptConfig, PromptModule } from "./types.js";
+
+/**
+ * Create a prompt module from a config object.
+ *
+ * Encapsulates template rendering (via LiquidJS) and variable validation
+ * (via Zod) into a single {@link PromptModule}. Works for both codegen
+ * output and runtime on-the-fly prompt construction.
+ *
+ * @param config - Prompt configuration with name, template, schema, and optional group.
+ * @returns A {@link PromptModule} with `render` and `validate` methods.
+ *
+ * @example
+ * ```ts
+ * import { createPrompt } from '@funkai/prompts'
+ * import { z } from 'zod'
+ *
+ * const greeting = createPrompt({
+ *   name: 'greeting',
+ *   template: 'Hello {{ name }}, welcome to {{ place }}!',
+ *   schema: z.object({ name: z.string(), place: z.string() }),
+ * })
+ *
+ * greeting.render({ name: 'Alice', place: 'Wonderland' })
+ * // => "Hello Alice, welcome to Wonderland!"
+ * ```
+ */
+export function createPrompt<T>(config: PromptConfig<T>): PromptModule<T> {
+  const { name, group, template, schema } = config;
+
+  return {
+    name,
+    group,
+    schema,
+    /**
+     * Render the prompt template with the given variables.
+     *
+     * @param variables - Template variables matching the prompt schema.
+     * @returns The rendered prompt string.
+     * @throws {ZodError} If variables fail schema validation.
+     */
+    render(variables: T): string {
+      return liquidEngine.parseAndRenderSync(
+        template,
+        schema.parse(variables) as Record<string, unknown>,
+      );
+    },
+    /**
+     * Validate variables against the prompt schema.
+     *
+     * @param variables - Variables to validate.
+     * @returns The parsed and validated variables.
+     * @throws {ZodError} If variables fail schema validation.
+     */
+    validate(variables: unknown): T {
+      return schema.parse(variables);
+    },
+  };
+}

package/src/registry.test.ts

@@ -1,31 +1,21 @@
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
 
+import { createPrompt } from "@/prompt.js";
 import { createPromptRegistry } from "@/registry.js";
 
-const mockPrompt = {
-  name: "test-prompt" as const,
-  group: "agents" as const,
+const mockPrompt = createPrompt({
+  name: "test-prompt",
+  group: "agents",
+  template: "Hello {{ name }}",
   schema: z.object({ name: z.string() }),
-  render(variables: { name: string }) {
-    return `Hello ${variables.name}`;
-  },
-  validate(variables: unknown) {
-    return z.object({ name: z.string() }).parse(variables);
-  },
-};
+});
 
-const emptyPrompt = {
-  name: "empty" as const,
-  group: undefined,
+const emptyPrompt = createPrompt({
+  name: "empty",
+  template: "static",
   schema: z.object({}),
-  render() {
-    return "static";
-  },
-  validate(variables: unknown) {
-    return z.object({}).parse(variables);
-  },
-};
+});
 
 describe(createPromptRegistry, () => {
   it("should provide dot-access to a registered prompt", () => {

package/src/registry.ts

@@ -55,16 +55,16 @@ function isPromptModule(value: unknown): value is PromptModule {
  * @private
  */
 function deepFreeze<T extends PromptNamespace>(obj: T): PromptRegistry<T> {
-  Object.freeze(obj);
-  for (const value of Object.values(obj)) {
-    if (
-      typeof value === "object" &&
-      value !== null &&
-      !Object.isFrozen(value) &&
-      !isPromptModule(value)
-    ) {
-      deepFreeze(value as PromptNamespace);
+  const copied = Object.entries(obj).reduce<Record<string, unknown>>((acc, [key, value]) => {
+    const isNamespace = typeof value === "object" && value !== null && !isPromptModule(value);
+    if (isNamespace) {
+      acc[key] = deepFreeze({ ...value } as PromptNamespace);
+    } else {
+      acc[key] = value;
     }
-  }
-  return obj as PromptRegistry<T>;
+    return acc;
+  }, {});
+
+  Object.freeze(copied);
+  return copied as PromptRegistry<T>;
 }

package/src/types.ts

@@ -10,7 +10,30 @@ export type CreateEngineOptions = Pick<
 >;
 
 /**
- * A single prompt module produced by codegen.
+ * Configuration for creating a prompt module via {@link createPrompt}.
+ *
+ * @example
+ * ```ts
+ * const config: PromptConfig<{ name: string }> = {
+ *   name: 'greeting',
+ *   template: 'Hello {{ name }}!',
+ *   schema: z.object({ name: z.string() }),
+ * }
+ * ```
+ */
+export interface PromptConfig<T = unknown> {
+  /** Kebab-case prompt identifier (e.g. `'greeting'`, `'worker-system'`). */
+  readonly name: string;
+  /** LiquidJS template string with `{{ variable }}` expressions. */
+  readonly template: string;
+  /** Zod schema for validating template variables. */
+  readonly schema: ZodType<T>;
+  /** Optional group path (e.g. `'agents'`, `'agents/core'`). */
+  readonly group?: string;
+}
+
+/**
+ * A single prompt module produced by {@link createPrompt} or codegen.
  *
  * Each `.prompt` file generates a default export conforming to this shape.
  */

package/tsconfig.json

@@ -5,21 +5,28 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "lib": ["ES2024"],
+    "types": ["node"],
+
     "strict": true,
-    "esModuleInterop": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true,
+
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
+
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
+
     "outDir": "./dist",
     "rootDir": ".",
     "paths": {
       "@/*": ["./src/*"]
-    },
-    "types": ["node"]
+    }
   },
   "include": ["src"],
   "exclude": ["node_modules", "dist"]

package/dist/lib/types-2PI_9h-M.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-2PI_9h-M.d.mts","names":[],"sources":["../../src/types.ts"],"mappings":";;;;;;AAMA;KAAY,mBAAA,GAAsB,IAAA,CAChC,aAAA;;;;AASF;;UAAiB,YAAA;EAAA,SACN,IAAA;EAAA,SACA,KAAA;EAAA,SACA,MAAA,EAAQ,OAAA,CAAQ,CAAA;EACzB,MAAA,CAAO,SAAA,EAAW,CAAA;EAClB,QAAA,CAAS,SAAA,YAAqB,CAAA;AAAA;;;;;UAOf,eAAA;EAAA,UACL,GAAA,WAAc,YAAA,GAAe,eAAA;AAAA;;;;;;;;AADzC;;;;;KAgBY,cAAA,WAAyB,eAAA,2BACd,CAAA,GAAI,CAAA,CAAE,CAAA,UAAW,YAAA,GAClC,CAAA,CAAE,CAAA,IACF,CAAA,CAAE,CAAA,UAAW,eAAA,GACX,cAAA,CAAe,CAAA,CAAE,CAAA,KACjB,CAAA,CAAE,CAAA"}