@fragno-dev/core 0.1.6 → 0.1.8

package/src/api/fragment-services.test.ts

@@ -0,0 +1,462 @@
+import { describe, test, expect, expectTypeOf } from "vitest";
+import { defineFragment } from "./fragment-builder";
+import { createFragment, instantiateFragment } from "./fragment-instantiation";
+
+// Test service interface definitions
+interface IEmailService {
+  sendEmail(to: string, subject: string, body: string): Promise<void>;
+}
+
+interface ILogger {
+  log(message: string): void;
+}
+
+describe("Fragment Service System", () => {
+  describe("usesService", () => {
+    test("should declare required service by default", () => {
+      const fragment = defineFragment<{}>("test-fragment").usesService<"email", IEmailService>(
+        "email",
+      );
+
+      expect(fragment.definition.usedServices).toBeDefined();
+      expect(fragment.definition.usedServices?.email).toEqual({ name: "email", required: true });
+    });
+
+    test("should declare optional service with { optional: true }", () => {
+      const fragment = defineFragment<{}>("test-fragment").usesService<"email", IEmailService>(
+        "email",
+        { optional: true },
+      );
+
+      expect(fragment.definition.usedServices).toBeDefined();
+      expect(fragment.definition.usedServices?.email).toEqual({ name: "email", required: false });
+    });
+
+    test("should support multiple required services", () => {
+      const fragment = defineFragment<{}>("test-fragment")
+        .usesService<"email", IEmailService>("email")
+        .usesService<"logger", ILogger>("logger");
+
+      expect(fragment.definition.usedServices?.email).toEqual({ name: "email", required: true });
+      expect(fragment.definition.usedServices?.logger).toEqual({ name: "logger", required: true });
+    });
+
+    test("should support mixing required and optional services", () => {
+      const fragment = defineFragment<{}>("test-fragment")
+        .usesService<"email", IEmailService>("email")
+        .usesService<"logger", ILogger>("logger", { optional: true });
+
+      expect(fragment.definition.usedServices?.email).toEqual({ name: "email", required: true });
+      expect(fragment.definition.usedServices?.logger).toEqual({ name: "logger", required: false });
+    });
+
+    test("should preserve other fragment properties", () => {
+      const fragment = defineFragment<{ apiKey: string }>("test-fragment")
+        .withDependencies(() => ({ dep: "value" }))
+        .usesService<"email", IEmailService>("email");
+
+      expect(fragment.definition.name).toBe("test-fragment");
+      expect(fragment.definition.usedServices?.email).toBeDefined();
+    });
+
+    test("should have correct type inference for required service", () => {
+      const fragment = defineFragment<{}>("test").usesService<"email", IEmailService>("email");
+
+      expectTypeOf(fragment).toMatchTypeOf<{
+        definition: {
+          usedServices?: {
+            email: { name: string; required: boolean };
+          };
+        };
+      }>();
+    });
+
+    test("should have correct type inference for optional service", () => {
+      const fragment = defineFragment<{}>("test").usesService<"logger", ILogger>("logger", {
+        optional: true,
+      });
+
+      expectTypeOf(fragment).toMatchTypeOf<{
+        definition: {
+          usedServices?: {
+            logger: { name: string; required: boolean };
+          };
+        };
+      }>();
+    });
+  });
+
+  describe("providesService", () => {
+    test("should declare provided service implementation", () => {
+      const emailImpl: IEmailService = {
+        sendEmail: async () => {},
+      };
+
+      const fragment = defineFragment<{}>("test-fragment").providesService(
+        "email",
+        ({ defineService }) => defineService(emailImpl),
+      );
+
+      expect(fragment.definition.providedServices).toBeDefined();
+    });
+
+    test("should support multiple provided services", () => {
+      const emailImpl: IEmailService = {
+        sendEmail: async () => {},
+      };
+
+      const loggerImpl: ILogger = {
+        log: () => {},
+      };
+
+      const _fragment = defineFragment<{}>("test-fragment")
+        .providesService("email", ({ defineService }) => defineService(emailImpl))
+        .providesService("logger", ({ defineService }) => defineService(loggerImpl));
+    });
+  });
+
+  describe("Service metadata", () => {
+    test("should store service metadata in definition", () => {
+      const fragment = defineFragment<{}>("test")
+        .usesService<"email", IEmailService>("email")
+        .usesService<"logger", ILogger>("logger", { optional: true });
+
+      expect(fragment.definition.usedServices?.email?.required).toBe(true);
+      expect(fragment.definition.usedServices?.logger?.required).toBe(false);
+    });
+
+    test("should store provided services in definition", () => {
+      const emailImpl: IEmailService = {
+        sendEmail: async () => {},
+      };
+
+      const fragment = defineFragment<{}>("test").providesService("email", ({ defineService }) =>
+        defineService(emailImpl),
+      );
+
+      expect(typeof fragment.definition.providedServices).toBe("object");
+    });
+
+    test("should allow fragments without any services", () => {
+      const fragment = defineFragment<{}>("test");
+
+      expect(fragment.definition.usedServices).toBeUndefined();
+      expect(fragment.definition.providedServices).toBeUndefined();
+    });
+  });
+
+  describe("Type safety", () => {
+    test("Unnamed services should have correct types (using defineService)", () => {
+      const fragment = defineFragment<{}>("test").providesService(({ defineService }) =>
+        defineService({
+          sendEmail: async () => {},
+        }),
+      );
+
+      const instance = createFragment(fragment, {}, [], {});
+      expect(instance.services.sendEmail).toBeDefined();
+      expectTypeOf<typeof instance.services.sendEmail>().toExtend<() => Promise<void>>();
+    });
+
+    test("Named services should have correct types (using defineService)", () => {
+      const fragment = defineFragment<{}>("test").providesService("email", ({ defineService }) =>
+        defineService({
+          sendEmail: async () => {},
+        }),
+      );
+
+      const instance = createFragment(fragment, {}, [], {});
+      expect(instance.services.email.sendEmail).toBeDefined();
+      expectTypeOf<typeof instance.services.email.sendEmail>().toExtend<() => Promise<void>>();
+    });
+
+    test("Unnamed services should have correct types (using object)", () => {
+      const fragment = defineFragment<{}>("test").providesService({
+        sendEmail: async () => {},
+      });
+
+      const instance = createFragment(fragment, {}, [], {});
+      expect(instance.services.sendEmail).toBeDefined();
+      expectTypeOf<typeof instance.services.sendEmail>().toExtend<() => Promise<void>>();
+    });
+
+    test("Unnamed services should have correct types (using callback with context)", () => {
+      const fragment = defineFragment<{}>("test").providesService(({ defineService }) =>
+        defineService({
+          sendEmail: async () => {},
+        }),
+      );
+
+      const instance = createFragment(fragment, {}, [], {});
+      expect(instance.services.sendEmail).toBeDefined();
+      expectTypeOf<typeof instance.services.sendEmail>().toExtend<() => Promise<void>>();
+    });
+
+    test("Unnamed services should have correct types (using 0-arity factory)", () => {
+      const fragment = defineFragment<{}>("test").providesService(() => ({
+        sendEmail: async () => {},
+      }));
+
+      const instance = createFragment(fragment, {}, [], {});
+      expect(instance.services.sendEmail).toBeDefined();
+      expectTypeOf<typeof instance.services.sendEmail>().toExtend<() => Promise<void>>();
+    });
+
+    test("Named services should have correct types (using object)", () => {
+      const fragment = defineFragment<{}>("test").providesService("email", {
+        sendEmail: async () => {},
+      });
+
+      const instance = createFragment(fragment, {}, [], {});
+      expect(instance.services.email.sendEmail).toBeDefined();
+      expectTypeOf<typeof instance.services.email.sendEmail>().toExtend<() => Promise<void>>();
+    });
+
+    test("usesService (required)", () => {
+      const fragment = defineFragment<{}>("test").usesService<"email", IEmailService>("email");
+
+      const emailImpl: IEmailService = {
+        sendEmail: async () => {},
+      };
+
+      const instance = createFragment(
+        fragment,
+        {},
+        [],
+        {},
+        {
+          email: emailImpl,
+        },
+      );
+
+      expectTypeOf<typeof instance.services.email.sendEmail>().toExtend<
+        (to: string, subject: string, body: string) => void
+      >();
+    });
+
+    test("usesService (required) - builder style", () => {
+      const fragment = defineFragment<{}>("test").usesService<"email", IEmailService>("email");
+
+      const emailImpl: IEmailService = {
+        sendEmail: async () => {},
+      };
+
+      const instance = instantiateFragment(fragment).withServices({ email: emailImpl }).build();
+
+      expectTypeOf<typeof instance.services.email.sendEmail>().toExtend<
+        (to: string, subject: string, body: string) => void
+      >();
+    });
+
+    test("usesService (optional)", () => {
+      const fragment = defineFragment<{}>("test").usesService<"email", IEmailService>("email", {
+        optional: true,
+      });
+
+      const instance = createFragment(fragment, {}, [], {});
+      // For optional services, the service itself might be undefined
+      expectTypeOf<typeof instance.services.email>().toExtend<IEmailService | undefined>();
+
+      // If provided, the service should have the correct type
+      if (instance.services.email) {
+        expectTypeOf<typeof instance.services.email.sendEmail>().toExtend<
+          (to: string, subject: string, body: string) => Promise<void>
+        >();
+      }
+    });
+
+    test("provided services should have correct types", () => {
+      const emailImpl: IEmailService = {
+        sendEmail: async () => {},
+      };
+
+      const fragment = defineFragment<{}>("test").providesService("email", ({ defineService }) =>
+        defineService(emailImpl),
+      );
+
+      // providedServices stores an object with service names as keys and factory functions as values
+      expect(fragment.definition.providedServices).toBeDefined();
+      expect(typeof fragment.definition.providedServices).toBe("object");
+    });
+
+    test("Named services should have correct types (using callback with context)", () => {
+      const fragment = defineFragment<{}>("test").providesService("email", ({ defineService }) =>
+        defineService({
+          sendEmail: async () => {},
+        }),
+      );
+
+      const instance = createFragment(fragment, {}, [], {});
+      expect(instance.services.email.sendEmail).toBeDefined();
+      expectTypeOf<typeof instance.services.email.sendEmail>().toExtend<() => Promise<void>>();
+    });
+
+    test("Named services should have correct types (using 0-arity factory)", () => {
+      const fragment = defineFragment<{}>("test").providesService("email", () => ({
+        sendEmail: async () => {},
+      }));
+
+      const instance = createFragment(fragment, {}, [], {});
+      expect(instance.services.email.sendEmail).toBeDefined();
+      expectTypeOf<typeof instance.services.email.sendEmail>().toExtend<() => Promise<void>>();
+    });
+  });
+
+  describe("Error handling", () => {
+    test("should throw error when required service is not provided", () => {
+      const fragment = defineFragment<{}>("test").usesService<"email", IEmailService>("email");
+
+      expect(() => {
+        createFragment(fragment, {}, [], {});
+      }).toThrow("Fragment 'test' requires service 'email' but it was not provided");
+    });
+
+    test("should not throw when optional service is not provided", () => {
+      const fragment = defineFragment<{}>("test").usesService<"email", IEmailService>("email", {
+        optional: true,
+      });
+
+      expect(() => {
+        createFragment(fragment, {}, [], {});
+      }).not.toThrow();
+    });
+  });
+
+  describe("Service dependencies and composition", () => {
+    test("provided service can access used services", () => {
+      const emailImpl: IEmailService = {
+        sendEmail: async () => {},
+      };
+
+      const fragment = defineFragment<{}>("test")
+        .usesService<"email", IEmailService>("email")
+        .providesService(({ deps }) => ({
+          sendWelcomeEmail: async (to: string) => {
+            await deps.email.sendEmail(to, "Welcome", "Welcome to our service!");
+          },
+        }));
+
+      const instance = createFragment(fragment, {}, [], {}, { email: emailImpl });
+
+      expect(instance.services.sendWelcomeEmail).toBeDefined();
+      expect(typeof instance.services.sendWelcomeEmail).toBe("function");
+    });
+
+    test("provided service can access used services - builder style", () => {
+      const emailImpl: IEmailService = {
+        sendEmail: async () => {},
+      };
+
+      const fragment = defineFragment<{}>("test")
+        .usesService<"email", IEmailService>("email")
+        .providesService(({ deps }) => ({
+          sendWelcomeEmail: async (to: string) => {
+            await deps.email.sendEmail(to, "Welcome", "Welcome to our service!");
+          },
+        }));
+
+      const instance = instantiateFragment(fragment).withServices({ email: emailImpl }).build();
+
+      expect(instance.services.sendWelcomeEmail).toBeDefined();
+      expect(typeof instance.services.sendWelcomeEmail).toBe("function");
+    });
+
+    test("provided service can access config", () => {
+      const fragment = defineFragment<{ apiKey: string }>("test").providesService(({ config }) => ({
+        getApiKey: () => config.apiKey,
+      }));
+
+      const instance = createFragment(fragment, { apiKey: "test-key" }, [], {});
+
+      expect(instance.services.getApiKey()).toBe("test-key");
+    });
+
+    test("provided service can access deps from withDependencies", () => {
+      const fragment = defineFragment<{ apiKey: string }>("test")
+        .withDependencies(({ config }) => ({
+          client: { key: config.apiKey },
+        }))
+        .providesService(({ deps }) => ({
+          getClient: () => deps.client,
+        }));
+
+      const instance = createFragment(fragment, { apiKey: "test-key" }, [], {});
+
+      expect(instance.services.getClient()).toEqual({ key: "test-key" });
+    });
+  });
+
+  describe("Service chaining and multiple services", () => {
+    test("should support chaining multiple provided services", () => {
+      const fragment = defineFragment<{}>("test")
+        .providesService("email", {
+          sendEmail: async () => {},
+        })
+        .providesService("logger", {
+          log: () => {},
+        });
+
+      const instance = createFragment(fragment, {}, [], {});
+      expect(instance.services.email.sendEmail).toBeDefined();
+      expect(instance.services.logger.log).toBeDefined();
+    });
+
+    test("should support mixing unnamed and named provided services", () => {
+      const fragment = defineFragment<{}>("test")
+        .providesService({
+          helper: () => "help",
+        })
+        .providesService("email", {
+          sendEmail: async () => {},
+        });
+
+      const instance = createFragment(fragment, {}, [], {});
+      expect(instance.services.helper).toBeDefined();
+      expect(instance.services.email.sendEmail).toBeDefined();
+    });
+  });
+
+  describe("Optional service runtime behavior", () => {
+    test("should handle optional service when not provided", () => {
+      const fragment = defineFragment<{}>("test")
+        .usesService<"email", IEmailService>("email", { optional: true })
+        .providesService(({ deps }) => ({
+          maybeSendEmail: async (to: string) => {
+            if (deps.email) {
+              await deps.email.sendEmail(to, "Subject", "Body");
+              return true;
+            }
+            return false;
+          },
+        }));
+
+      const instance = createFragment(fragment, {}, [], {});
+
+      expect(instance.services.maybeSendEmail).toBeDefined();
+      // Should not throw when optional service is not provided
+    });
+
+    test("should handle optional service when provided", () => {
+      const emailImpl: IEmailService = {
+        sendEmail: async () => {},
+      };
+
+      const fragment = defineFragment<{}>("test")
+        .usesService<"email", IEmailService>("email", { optional: true })
+        .providesService(({ deps }) => ({
+          maybeSendEmail: async (to: string) => {
+            if (deps.email) {
+              await deps.email.sendEmail(to, "Subject", "Body");
+              return true;
+            }
+            return false;
+          },
+        }));
+
+      const instance = createFragment(fragment, {}, [], {}, { email: emailImpl });
+
+      expect(instance.services.email).toBeDefined();
+      expect(instance.services.maybeSendEmail).toBeDefined();
+    });
+  });
+});

package/src/api/fragment.test.ts

@@ -58,7 +58,7 @@ describe("new-fragment API", () => {
       >();
     });
 
-    test("withServices has access to dependencies and config", () => {
+    test("providesService has access to dependencies and config", () => {
       const _config = {
         apiKey: "test-key",
         baseUrl: "https://api.example.com",
@@ -73,11 +73,11 @@ describe("new-fragment API", () => {
 
           return { httpClient: { baseUrl: config.baseUrl } };
         })
-        .withServices(({ config, deps }) => {
+        .providesService(({ config, deps, defineService }) => {
           expectTypeOf(config).toEqualTypeOf<typeof _config>();
           expectTypeOf(deps).toEqualTypeOf<{ httpClient: { baseUrl: string } }>();
 
-          return {
+          return defineService({
             userService: {
               getUser: async (id: string) => ({ id, name: "Test User" }),
             },
@@ -85,7 +85,7 @@ describe("new-fragment API", () => {
               get: (_key: string): string => crypto.randomUUID(),
               set: (_key: string, _value: string) => {},
             },
-          };
+          });
         });
 
       expectTypeOf<typeof _fragment>().toEqualTypeOf<
@@ -165,7 +165,9 @@ describe("new-fragment API", () => {
       expectTypeOf(lib2).toEqualTypeOf<
         FragmentBuilder<typeof _config, { dep1: string }, Empty, Empty>
       >();
-      const lib3 = lib2.withServices(() => ({ service1: "value1" }));
+      const lib3 = lib2.providesService(({ defineService }) =>
+        defineService({ service1: "value1" }),
+      );
       expectTypeOf(lib3).toEqualTypeOf<
         FragmentBuilder<typeof _config, { dep1: string }, { service1: string }, Empty>
       >();
@@ -182,9 +184,11 @@ describe("new-fragment API", () => {
         .withDependencies(({ config }) => ({
           client: `Client for ${config.apiKey}`,
         }))
-        .withServices(({ deps }) => ({
-          service: `Service using ${deps.client}`,
-        }));
+        .providesService(({ deps, defineService }) =>
+          defineService({
+            service: `Service using ${deps.client}`,
+          }),
+        );
 
       expect(fragment.definition.name).toBe("my-lib");
       expect(fragment.definition.dependencies).toBeDefined();
@@ -220,9 +224,11 @@ describe("new-fragment API", () => {
         .withDependencies(() => ({
           formatter: (s: string) => s.toUpperCase(),
         }))
-        .withServices(() => ({
-          logger: { log: (s: string) => console.log(s) },
-        }));
+        .providesService(({ defineService }) =>
+          defineService({
+            logger: { log: (s: string) => console.log(s) },
+          }),
+        );
 
       const fragment = createFragment(fragmentDef, { prefix: "Hello" }, [routeFactory], {});
 
@@ -297,7 +303,7 @@ describe("new-fragment API", () => {
 
       const fragmentDef = defineFragment("test")
         .withDependencies(() => ({ tool: "hammer" }))
-        .withServices(() => ({ storage: "memory" }));
+        .providesService(({ defineService }) => defineService({ storage: "memory" }));
 
       createFragment(fragmentDef, { setting: "value" }, [routeFactory], {});
 
@@ -309,11 +315,13 @@ describe("new-fragment API", () => {
 
   describe("Type constraints", () => {
     test("Services must extend Record<string, unknown>", () => {
-      const fragmentDef = defineFragment("test").withServices(() => ({
-        validService: { method: () => {} },
-        anotherService: "string value",
-        numberService: 123,
-      }));
+      const fragmentDef = defineFragment("test").providesService(({ defineService }) =>
+        defineService({
+          validService: { method: () => {} },
+          anotherService: "string value",
+          numberService: 123,
+        }),
+      );
 
       const _fragment = createFragment(fragmentDef, {}, [], {});
 
@@ -534,4 +542,44 @@ describe("new-fragment API", () => {
       expect(fragment.mountRoute).toBe("/custom");
     });
   });
+
+  describe("Route handler this context", () => {
+    test("this context type is RequestThisContext for standard fragments", () => {
+      const fragmentDef = defineFragment("test");
+
+      const routesFactory = defineRoutes().create(() => {
+        return [
+          defineRoute({
+            method: "GET",
+            path: "/test",
+            handler: async function (_, { json }) {
+              // this should be RequestThisContext
+              // (we can't easily test the exact type due to how TypeScript handles 'this')
+              expect(this).toBeDefined();
+              expect(typeof this).toBe("object");
+              return json({ ok: true });
+            },
+          }),
+        ];
+      });
+
+      const _fragment = createFragment(fragmentDef, {}, [routesFactory], {});
+      expect(_fragment).toBeDefined();
+    });
+
+    test("defineRoute without defineRoutes defaults to RequestThisContext", () => {
+      const route = defineRoute({
+        method: "GET",
+        path: "/test",
+        handler: async function (_, { json }) {
+          // this defaults to RequestThisContext
+          expect(this).toBeDefined();
+          expect(typeof this).toBe("object");
+          return json({ ok: true });
+        },
+      });
+
+      expect(route).toBeDefined();
+    });
+  });
 });

package/src/api/internal/path-type.test.ts

@@ -446,39 +446,39 @@ test("MaybeExtractPathParamsOrWiden type tests", () => {
 test("QueryParamsHint type tests", () => {
   // Basic usage with string union
   expectTypeOf<QueryParamsHint<"page" | "limit">>().toEqualTypeOf<
-    Partial<Record<"page" | "limit", string>> & Record<string, string>
+    Partial<Record<"page" | "limit", string>> & Record<string, string | undefined>
   >();
 
   // Single parameter hint
   expectTypeOf<QueryParamsHint<"search">>().toEqualTypeOf<
-    Partial<Record<"search", string>> & Record<string, string>
+    Partial<Record<"search", string>> & Record<string, string | undefined>
   >();
 
   // Empty hint (never) - should still allow any string keys
   expectTypeOf<QueryParamsHint<never>>().toEqualTypeOf<
-    Partial<Record<never, string>> & Record<string, string>
+    Partial<Record<never, string>> & Record<string, string | undefined>
   >();
 
   // With custom value type
   expectTypeOf<QueryParamsHint<"page" | "limit", number>>().toEqualTypeOf<
-    Partial<Record<"page" | "limit", number>> & Record<string, number>
+    Partial<Record<"page" | "limit", number>> & Record<string, number | undefined>
   >();
 
   // With boolean value type
   expectTypeOf<QueryParamsHint<"enabled" | "debug", boolean>>().toEqualTypeOf<
-    Partial<Record<"enabled" | "debug", boolean>> & Record<string, boolean>
+    Partial<Record<"enabled" | "debug", boolean>> & Record<string, boolean | undefined>
   >();
 
   // With union value type
   type StringOrNumber = string | number;
   expectTypeOf<QueryParamsHint<"value", StringOrNumber>>().toEqualTypeOf<
-    Partial<Record<"value", StringOrNumber>> & Record<string, StringOrNumber>
+    Partial<Record<"value", StringOrNumber>> & Record<string, StringOrNumber | undefined>
   >();
 
   // With custom object type
   type CustomType = { raw: string; parsed: boolean };
   expectTypeOf<QueryParamsHint<"data", CustomType>>().toEqualTypeOf<
-    Partial<Record<"data", CustomType>> & Record<string, CustomType>
+    Partial<Record<"data", CustomType>> & Record<string, CustomType | undefined>
   >();
 });
 

package/src/api/internal/path.ts

@@ -124,7 +124,7 @@ export type HasPathParams<T extends string> = ExtractPathParamNames<T> extends n
 export type QueryParamsHint<TQueryParameters extends string, ValueType = string> = Partial<
   Record<TQueryParameters, ValueType>
 > &
-  Record<string, ValueType>;
+  Record<string, ValueType | undefined>;
 
 // Runtime utilities
 

package/src/api/request-middleware.test.ts

@@ -9,9 +9,12 @@ describe("Request Middleware", () => {
   test("middleware can intercept and return early", async () => {
     const config = { apiKey: "test" };
 
-    const fragment = defineFragment<typeof config>("test-lib").withServices(() => ({
-      auth: { isAuthorized: (token?: string) => token === "valid-token" },
-    }));
+    const fragment = defineFragment<typeof config>("test-lib").providesService(
+      ({ defineService }) =>
+        defineService({
+          auth: { isAuthorized: (token?: string) => token === "valid-token" },
+        }),
+    );
 
     const routes = [
       defineRoute({