@emkodev/emkore 1.0.3

package/test/unit/api-definition.test.ts

@@ -0,0 +1,628 @@
+import { test, expect, describe } from "bun:test";
+import {
+  type ApiDefinition,
+  apiDefinitionToJsonSchema,
+} from "../../src/common/llm/api-definition.type.ts";
+
+describe("apiDefinitionToJsonSchema - Primitive parameter types", () => {
+  test("should handle string parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Test Function",
+      description: "A test function",
+      parameters: [
+        {
+          name: "username",
+          description: "User name",
+          type: "string",
+          isRequired: true,
+        },
+      ],
+      returns: {
+        type: "string",
+        description: "Result",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.username).toEqual({
+      type: "string",
+      description: "User name",
+    });
+    expect(schema.parameters.required).toEqual(["username"]);
+  });
+
+  test("should handle number parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Calculate",
+      description: "Calculate something",
+      parameters: [
+        {
+          name: "amount",
+          description: "The amount",
+          type: "number",
+        },
+      ],
+      returns: {
+        type: "number",
+        description: "Result",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.amount).toEqual({
+      type: "number",
+      description: "The amount",
+    });
+    expect(schema.parameters.required).toEqual(["amount"]);
+  });
+
+  test("should handle integer parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Count",
+      description: "Count items",
+      parameters: [
+        {
+          name: "count",
+          description: "Item count",
+          type: "integer",
+        },
+      ],
+      returns: {
+        type: "integer",
+        description: "Total",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.count).toEqual({
+      type: "integer",
+      description: "Item count",
+    });
+  });
+
+  test("should handle boolean parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Toggle",
+      description: "Toggle a flag",
+      parameters: [
+        {
+          name: "isActive",
+          description: "Active flag",
+          type: "boolean",
+        },
+      ],
+      returns: {
+        type: "boolean",
+        description: "New state",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.isActive).toEqual({
+      type: "boolean",
+      description: "Active flag",
+    });
+  });
+
+  test("should handle null parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Reset",
+      description: "Reset value",
+      parameters: [
+        {
+          name: "value",
+          description: "Nullable value",
+          type: "null",
+        },
+      ],
+      returns: {
+        type: "null",
+        description: "Null result",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.value).toEqual({
+      type: "null",
+      description: "Nullable value",
+    });
+  });
+});
+
+describe("apiDefinitionToJsonSchema - Array parameters with items", () => {
+  test("should include items for array parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Process List",
+      description: "Process a list",
+      parameters: [
+        {
+          name: "ids",
+          description: "List of IDs",
+          type: "array",
+          items: {
+            type: "string",
+            description: "ID value",
+          },
+        },
+      ],
+      returns: {
+        type: "array",
+        description: "Processed results",
+        items: {
+          type: "object",
+          description: "Result object",
+        },
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.ids).toEqual({
+      type: "array",
+      description: "List of IDs",
+      items: {
+        type: "string",
+        description: "ID value",
+      },
+    });
+
+    expect(schema.returns).toEqual({
+      type: "array",
+      description: "Processed results",
+      items: {
+        type: "object",
+        description: "Result object",
+      },
+    });
+  });
+
+  test("should handle array of objects with properties", () => {
+    const definition: ApiDefinition = {
+      name: "Create Users",
+      description: "Create multiple users",
+      parameters: [
+        {
+          name: "users",
+          description: "User list",
+          type: "array",
+          items: {
+            type: "object",
+            description: "User data",
+            properties: {
+              name: { type: "string" },
+              email: { type: "string" },
+            },
+          },
+        },
+      ],
+      returns: {
+        type: "array",
+        description: "Created users",
+        items: {
+          type: "object",
+          properties: {
+            id: { type: "string" },
+            name: { type: "string" },
+          },
+        },
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.users.items.properties).toEqual({
+      name: { type: "string" },
+      email: { type: "string" },
+    });
+
+    expect(schema.returns.items.properties).toEqual({
+      id: { type: "string" },
+      name: { type: "string" },
+    });
+  });
+});
+
+describe("apiDefinitionToJsonSchema - Object parameters with properties", () => {
+  test("should include properties for object parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Create User",
+      description: "Create a user",
+      parameters: [
+        {
+          name: "user",
+          description: "User data",
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Full name" },
+            email: { type: "string", description: "Email address" },
+            age: { type: "integer", description: "Age in years" },
+          },
+        },
+      ],
+      returns: {
+        type: "object",
+        description: "Created user",
+        properties: {
+          id: { type: "string" },
+          name: { type: "string" },
+          createdAt: { type: "string" },
+        },
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.user).toEqual({
+      type: "object",
+      description: "User data",
+      properties: {
+        name: { type: "string", description: "Full name" },
+        email: { type: "string", description: "Email address" },
+        age: { type: "integer", description: "Age in years" },
+      },
+    });
+
+    expect(schema.returns.properties).toEqual({
+      id: { type: "string" },
+      name: { type: "string" },
+      createdAt: { type: "string" },
+    });
+  });
+
+  test("should include required field for object parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Update Profile",
+      description: "Update user profile",
+      parameters: [
+        {
+          name: "profile",
+          description: "Profile data",
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            bio: { type: "string" },
+          },
+          required: ["name"],
+        },
+      ],
+      returns: {
+        type: "object",
+        description: "Updated profile",
+        properties: {
+          name: { type: "string" },
+        },
+        required: ["name"],
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.profile.required).toEqual(["name"]);
+    expect(schema.returns.required).toEqual(["name"]);
+  });
+
+  test("should handle object without properties field", () => {
+    const definition: ApiDefinition = {
+      name: "Store Data",
+      description: "Store arbitrary data",
+      parameters: [
+        {
+          name: "data",
+          description: "Data object",
+          type: "object",
+        },
+      ],
+      returns: {
+        type: "object",
+        description: "Stored data",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.data).toEqual({
+      type: "object",
+      description: "Data object",
+    });
+
+    expect(schema.returns).toEqual({
+      type: "object",
+      description: "Stored data",
+    });
+  });
+});
+
+describe("apiDefinitionToJsonSchema - Required vs optional parameters", () => {
+  test("should mark parameters as required by default", () => {
+    const definition: ApiDefinition = {
+      name: "Test",
+      description: "Test function",
+      parameters: [
+        {
+          name: "param1",
+          description: "First param",
+          type: "string",
+        },
+        {
+          name: "param2",
+          description: "Second param",
+          type: "number",
+        },
+      ],
+      returns: {
+        type: "string",
+        description: "Result",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.required).toEqual(["param1", "param2"]);
+  });
+
+  test("should handle explicitly required parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Test",
+      description: "Test function",
+      parameters: [
+        {
+          name: "required1",
+          description: "Required param",
+          type: "string",
+          isRequired: true,
+        },
+      ],
+      returns: {
+        type: "string",
+        description: "Result",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.required).toEqual(["required1"]);
+  });
+
+  test("should handle optional parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Test",
+      description: "Test function",
+      parameters: [
+        {
+          name: "required",
+          description: "Required param",
+          type: "string",
+          isRequired: true,
+        },
+        {
+          name: "optional",
+          description: "Optional param",
+          type: "string",
+          isRequired: false,
+        },
+      ],
+      returns: {
+        type: "string",
+        description: "Result",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.required).toEqual(["required"]);
+    expect(schema.parameters.properties.optional).toEqual({
+      type: "string",
+      description: "Optional param",
+    });
+  });
+
+  test("should handle all optional parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Test",
+      description: "Test function",
+      parameters: [
+        {
+          name: "opt1",
+          description: "Optional param 1",
+          type: "string",
+          isRequired: false,
+        },
+        {
+          name: "opt2",
+          description: "Optional param 2",
+          type: "number",
+          isRequired: false,
+        },
+      ],
+      returns: {
+        type: "string",
+        description: "Result",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.required).toEqual([]);
+  });
+});
+
+describe("apiDefinitionToJsonSchema - Empty parameters", () => {
+  test("should handle function with no parameters", () => {
+    const definition: ApiDefinition = {
+      name: "Get Time",
+      description: "Get current time",
+      parameters: [],
+      returns: {
+        type: "string",
+        description: "Current timestamp",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties).toEqual({});
+    expect(schema.parameters.required).toEqual([]);
+    expect(schema.returns).toEqual({
+      type: "string",
+      description: "Current timestamp",
+    });
+  });
+});
+
+describe("apiDefinitionToJsonSchema - Complex nested structures", () => {
+  test("should handle deeply nested object structures", () => {
+    const definition: ApiDefinition = {
+      name: "Create Order",
+      description: "Create a new order",
+      parameters: [
+        {
+          name: "order",
+          description: "Order details",
+          type: "object",
+          properties: {
+            customer: {
+              type: "object",
+              properties: {
+                name: { type: "string" },
+                email: { type: "string" },
+              },
+            },
+            items: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  productId: { type: "string" },
+                  quantity: { type: "integer" },
+                },
+              },
+            },
+          },
+          required: ["customer", "items"],
+        },
+      ],
+      returns: {
+        type: "object",
+        description: "Created order",
+        properties: {
+          orderId: { type: "string" },
+          status: { type: "string" },
+        },
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.order.properties.customer).toEqual({
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        email: { type: "string" },
+      },
+    });
+
+    expect(schema.parameters.properties.order.properties.items).toEqual({
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          productId: { type: "string" },
+          quantity: { type: "integer" },
+        },
+      },
+    });
+
+    expect(schema.parameters.properties.order.required).toEqual([
+      "customer",
+      "items",
+    ]);
+  });
+});
+
+describe("apiDefinitionToJsonSchema - Metadata preservation", () => {
+  test("should preserve name and description", () => {
+    const definition: ApiDefinition = {
+      name: "Calculate Tax",
+      description: "Calculate tax amount based on subtotal",
+      parameters: [
+        {
+          name: "subtotal",
+          description: "Subtotal amount",
+          type: "number",
+        },
+      ],
+      returns: {
+        type: "number",
+        description: "Tax amount",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.name).toEqual("Calculate Tax");
+    expect(schema.description).toEqual(
+      "Calculate tax amount based on subtotal",
+    );
+  });
+
+  test("should preserve parameter descriptions", () => {
+    const definition: ApiDefinition = {
+      name: "Test",
+      description: "Test function",
+      parameters: [
+        {
+          name: "email",
+          description: "User email address in RFC 5322 format",
+          type: "string",
+        },
+      ],
+      returns: {
+        type: "boolean",
+        description: "True if email is valid",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    expect(schema.parameters.properties.email.description).toEqual(
+      "User email address in RFC 5322 format",
+    );
+    expect(schema.returns.description).toEqual("True if email is valid");
+  });
+});
+
+describe("apiDefinitionToJsonSchema - JSON Schema structure", () => {
+  test("should output valid JSON Schema structure", () => {
+    const definition: ApiDefinition = {
+      name: "Test Function",
+      description: "A test",
+      parameters: [
+        {
+          name: "param1",
+          description: "First param",
+          type: "string",
+        },
+      ],
+      returns: {
+        type: "string",
+        description: "Result",
+      },
+    };
+
+    const schema = apiDefinitionToJsonSchema(definition);
+
+    // Verify top-level structure
+    expect(typeof schema.name).toEqual("string");
+    expect(typeof schema.description).toEqual("string");
+    expect(typeof schema.parameters).toEqual("object");
+    expect(schema.parameters.type).toEqual("object");
+    expect(typeof schema.parameters.properties).toEqual("object");
+    expect(Array.isArray(schema.parameters.required)).toEqual(true);
+    expect(typeof schema.returns).toEqual("object");
+  });
+});