@fragno-dev/core 0.1.10 → 0.2.0

package/src/api/fragment-definition-builder.ts

@@ -24,12 +24,12 @@ export type LinkedFragmentCallback<
   TConfig,
   TOptions extends FragnoPublicConfig,
   TServiceDependencies,
+  TFragment extends AnyFragnoInstantiatedFragment = AnyFragnoInstantiatedFragment,
 > = (context: {
   config: TConfig;
   options: TOptions;
   serviceDependencies?: TServiceDependencies;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-}) => FragnoInstantiatedFragment<any, any, any, any, any, any, any>;
+}) => TFragment;
 
 /**
  * Extract the services type from a FragnoInstantiatedFragment
@@ -223,12 +223,27 @@ export interface FragmentDefinition<
     deps: TDeps;
   }) => RequestContextStorage<TRequestStorage>;
 
+  /**
+   * Optional factory for internal data attached to fragment.$internal.
+   */
+  internalDataFactory?: (context: {
+    config: TConfig;
+    options: TOptions;
+    deps: TDeps;
+    linkedFragments: TLinkedFragments;
+  }) => Record<string, unknown> | void;
+
   /**
    * Optional linked fragments that will be automatically instantiated with this fragment.
    * Linked fragments are service-only and share the same config/options as the parent.
    */
   linkedFragments?: {
-    [K in keyof TLinkedFragments]: LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies>;
+    [K in keyof TLinkedFragments]: LinkedFragmentCallback<
+      TConfig,
+      TOptions,
+      TServiceDependencies,
+      TLinkedFragments[K]
+    >;
   };
 
   $serviceThisContext?: TServiceThisContext;
@@ -307,7 +322,12 @@ export class FragmentDefinitionBuilder<
     deps: TDeps;
   }) => RequestContextStorage<TRequestStorage>;
   #linkedFragments?: {
-    [K in keyof TLinkedFragments]: LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies>;
+    [K in keyof TLinkedFragments]: LinkedFragmentCallback<
+      TConfig,
+      TOptions,
+      TServiceDependencies,
+      TLinkedFragments[K]
+    >;
   };
 
   constructor(
@@ -368,7 +388,8 @@ export class FragmentDefinitionBuilder<
         [K in keyof TLinkedFragments]: LinkedFragmentCallback<
           TConfig,
           TOptions,
-          TServiceDependencies
+          TServiceDependencies,
+          TLinkedFragments[K]
         >;
       };
     },
@@ -966,15 +987,13 @@ export class FragmentDefinitionBuilder<
 
   /**
    * Register a linked fragment that will be automatically instantiated.
-   * Linked fragments are service-only (no routes) and share the same config/options as the parent.
-   * All services from the linked fragment will be available as private services.
+   * Linked fragments share the same config/options as the parent and their services
+   * are exposed as private services. Routes are not exposed by default, but the
+   * instantiator may mount internal linked fragment routes under an internal prefix.
    */
-  withLinkedFragment<
-    const TName extends string,
-    TCallback extends LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies>,
-  >(
+  withLinkedFragment<const TName extends string, TFragment extends AnyFragnoInstantiatedFragment>(
     name: TName,
-    callback: TCallback,
+    callback: LinkedFragmentCallback<TConfig, TOptions, TServiceDependencies, TFragment>,
   ): FragmentDefinitionBuilder<
     TConfig,
     TOptions,
@@ -982,18 +1001,18 @@ export class FragmentDefinitionBuilder<
     TBaseServices,
     TServices,
     TServiceDependencies,
-    TPrivateServices & ExtractLinkedServices<TCallback>,
+    TPrivateServices & ExtractLinkedServices<() => TFragment>,
     TServiceThisContext,
     THandlerThisContext,
     TRequestStorage,
-    TLinkedFragments & { [K in TName]: ReturnType<TCallback> }
+    TLinkedFragments & { [K in TName]: TFragment }
   > {
     const newLinkedFragments = {
       ...this.#linkedFragments,
       [name]: callback,
     };
 
-    // Cast is safe: We're declaring that the returned builder has TPrivateServices & ExtractLinkedServices<TCallback>,
+    // Cast is safe: We're declaring that the returned builder has TPrivateServices & ExtractLinkedServices<TFragment>,
     // even though the runtime privateServices hasn't changed yet. The linked fragment services will be
     // merged into privateServices at instantiation time by the instantiator.
     return new FragmentDefinitionBuilder(this.#name, {
@@ -1013,11 +1032,11 @@ export class FragmentDefinitionBuilder<
       TBaseServices,
       TServices,
       TServiceDependencies,
-      TPrivateServices & ExtractLinkedServices<TCallback>,
+      TPrivateServices & ExtractLinkedServices<() => TFragment>,
       TServiceThisContext,
       THandlerThisContext,
       TRequestStorage,
-      TLinkedFragments & { [K in TName]: ReturnType<TCallback> }
+      TLinkedFragments & { [K in TName]: TFragment }
     >;
   }
 

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

@@ -1,6 +1,10 @@
 import { describe, it, expect, vi, expectTypeOf } from "vitest";
 import { defineFragment } from "./fragment-definition-builder";
-import { instantiate, FragnoInstantiatedFragment } from "./fragment-instantiator";
+import {
+  instantiate,
+  instantiateFragment,
+  FragnoInstantiatedFragment,
+} from "./fragment-instantiator";
 import { defineRoute, defineRoutes, type AnyFragmentDefinition } from "./route";
 import type { FragnoPublicConfig } from "./shared-types";
 import type { RequestThisContext } from "./api";
@@ -412,6 +416,56 @@ describe("fragment-instantiator", () => {
       expect(data).toEqual({ userId: "123" });
     });
 
+    it("should URL decode path params", async () => {
+      const definition = defineFragment("test-fragment").build();
+
+      const route = defineRoute({
+        method: "GET",
+        path: "/users/:name",
+        handler: async (input, { json }) => {
+          return json({ userName: input.pathParams.name });
+        },
+      });
+
+      const fragment = instantiate(definition)
+        .withRoutes([route])
+        .withOptions({ mountRoute: "/api" })
+        .build();
+
+      // URL with encoded space: "a%20b" should be decoded to "a b"
+      const request = new Request("http://localhost/api/users/a%20b");
+      const response = await fragment.handler(request);
+
+      expect(response.status).toBe(200);
+      const data = await response.json();
+      expect(data).toEqual({ userName: "a b" });
+    });
+
+    it("should URL decode path params with special characters", async () => {
+      const definition = defineFragment("test-fragment").build();
+
+      const route = defineRoute({
+        method: "GET",
+        path: "/files/:path",
+        handler: async (input, { json }) => {
+          return json({ filePath: input.pathParams.path });
+        },
+      });
+
+      const fragment = instantiate(definition)
+        .withRoutes([route])
+        .withOptions({ mountRoute: "/api" })
+        .build();
+
+      // URL with encoded slash: "folder%2Fsubfolder" should be decoded to "folder/subfolder"
+      const request = new Request("http://localhost/api/files/folder%2Fsubfolder");
+      const response = await fragment.handler(request);
+
+      expect(response.status).toBe(200);
+      const data = await response.json();
+      expect(data).toEqual({ filePath: "folder/subfolder" });
+    });
+
     it("should handle POST requests with body", async () => {
       const definition = defineFragment("test-fragment").build();
 
@@ -446,6 +500,170 @@ describe("fragment-instantiator", () => {
       const data = await response.json();
       expect(data).toEqual({ received: { test: "data" } });
     });
+
+    it("should accept FormData for routes with contentType: multipart/form-data", async () => {
+      const definition = defineFragment("test-fragment").build();
+
+      const route = defineRoute({
+        method: "POST",
+        path: "/upload",
+        contentType: "multipart/form-data",
+        handler: async (ctx, { json }) => {
+          const formData = ctx.formData();
+          const description = formData.get("description") as string;
+          return json({ description });
+        },
+      });
+
+      const fragment = instantiate(definition)
+        .withRoutes([route])
+        .withOptions({ mountRoute: "/api" })
+        .build();
+
+      const formData = new FormData();
+      formData.append("description", "Test file upload");
+
+      const request = new Request("http://localhost/api/upload", {
+        method: "POST",
+        body: formData,
+      });
+
+      const response = await fragment.handler(request);
+
+      expect(response.status).toBe(200);
+      const data = await response.json();
+      expect(data).toEqual({ description: "Test file upload" });
+    });
+
+    it("should reject FormData for JSON routes (default contentType)", async () => {
+      const definition = defineFragment("test-fragment").build();
+
+      const route = defineRoute({
+        method: "POST",
+        path: "/json-only",
+        inputSchema: z.object({ name: z.string() }),
+        handler: async ({ input }, { json }) => {
+          const body = await input.valid();
+          return json(body);
+        },
+      });
+
+      const fragment = instantiate(definition)
+        .withRoutes([route])
+        .withOptions({ mountRoute: "/api" })
+        .build();
+
+      const formData = new FormData();
+      formData.append("name", "test");
+
+      const request = new Request("http://localhost/api/json-only", {
+        method: "POST",
+        body: formData,
+      });
+
+      const response = await fragment.handler(request);
+
+      expect(response.status).toBe(415);
+      const data = await response.json();
+      expect(data.code).toBe("UNSUPPORTED_MEDIA_TYPE");
+    });
+
+    it("should reject JSON for FormData routes", async () => {
+      const definition = defineFragment("test-fragment").build();
+
+      const route = defineRoute({
+        method: "POST",
+        path: "/upload",
+        contentType: "multipart/form-data",
+        handler: async (ctx, { json }) => {
+          // Verify formData() works (would throw if not FormData)
+          ctx.formData();
+          return json({ success: true });
+        },
+      });
+
+      const fragment = instantiate(definition)
+        .withRoutes([route])
+        .withOptions({ mountRoute: "/api" })
+        .build();
+
+      const request = new Request("http://localhost/api/upload", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name: "test" }),
+      });
+
+      const response = await fragment.handler(request);
+
+      expect(response.status).toBe(415);
+      const data = await response.json();
+      expect(data.code).toBe("UNSUPPORTED_MEDIA_TYPE");
+    });
+
+    it("should accept octet-stream for routes with contentType: application/octet-stream", async () => {
+      const definition = defineFragment("test-fragment").build();
+
+      const route = defineRoute({
+        method: "PUT",
+        path: "/stream",
+        contentType: "application/octet-stream",
+        handler: async (ctx, { json }) => {
+          const stream = ctx.bodyStream();
+          const text = await new Response(stream).text();
+          return json({ received: text });
+        },
+      });
+
+      const fragment = instantiate(definition)
+        .withRoutes([route])
+        .withOptions({ mountRoute: "/api" })
+        .build();
+
+      const request = new Request("http://localhost/api/stream", {
+        method: "PUT",
+        headers: { "Content-Type": "application/octet-stream" },
+        body: new TextEncoder().encode("hello"),
+      });
+
+      const response = await fragment.handler(request);
+
+      expect(response.status).toBe(200);
+      const data = await response.json();
+      expect(data).toEqual({ received: "hello" });
+    });
+
+    it("should reject JSON for octet-stream routes", async () => {
+      const definition = defineFragment("test-fragment").build();
+
+      const route = defineRoute({
+        method: "PUT",
+        path: "/stream",
+        contentType: "application/octet-stream",
+        handler: async (ctx, { json }) => {
+          if (!ctx.isBodyStream()) {
+            throw new Error("Expected stream body");
+          }
+          return json({ ok: true });
+        },
+      });
+
+      const fragment = instantiate(definition)
+        .withRoutes([route])
+        .withOptions({ mountRoute: "/api" })
+        .build();
+
+      const request = new Request("http://localhost/api/stream", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ hello: "world" }),
+      });
+
+      const response = await fragment.handler(request);
+
+      expect(response.status).toBe(415);
+      const data = await response.json();
+      expect(data.code).toBe("UNSUPPORTED_MEDIA_TYPE");
+    });
   });
 
   describe("callRoute", () => {
@@ -1281,6 +1499,78 @@ describe("fragment-instantiator", () => {
       expect(linkedFragment?.name).toBe("linked-fragment");
     });
 
+    it("should mount internal linked fragment routes under /_internal", async () => {
+      const linkedFragmentDef = defineFragment("linked-fragment").build();
+      const linkedRoutes = defineRoutes(linkedFragmentDef).create(({ defineRoute }) => [
+        defineRoute({
+          method: "GET",
+          path: "/status",
+          handler: async (_input, { json }) => {
+            return json({ ok: true });
+          },
+        }),
+      ]);
+
+      const definition = defineFragment("main-fragment")
+        .withLinkedFragment("_fragno_internal", ({ config, options }) => {
+          return instantiate(linkedFragmentDef)
+            .withConfig(config)
+            .withOptions(options)
+            .withRoutes([linkedRoutes])
+            .build();
+        })
+        .build();
+
+      const fragment = instantiate(definition).withOptions({}).build();
+
+      const response = await fragment.callRouteRaw("GET", "/_internal/status" as never);
+      expect(response.status).toBe(200);
+      await expect(response.json()).resolves.toEqual({ ok: true });
+    });
+
+    it("should run middleware set on the internal fragment", async () => {
+      const linkedFragmentDef = defineFragment("linked-fragment").build();
+      const linkedRoutes = defineRoutes(linkedFragmentDef).create(({ defineRoute }) => [
+        defineRoute({
+          method: "GET",
+          path: "/status",
+          handler: async (_input, { json }) => {
+            return json({ ok: true });
+          },
+        }),
+      ]);
+
+      const definition = defineFragment("main-fragment")
+        .withLinkedFragment("_fragno_internal", ({ config, options }) => {
+          return instantiate(linkedFragmentDef)
+            .withConfig(config)
+            .withOptions(options)
+            .withRoutes([linkedRoutes])
+            .build();
+        })
+        .build();
+
+      const fragment = instantiate(definition).withOptions({ mountRoute: "/api" }).build();
+
+      const internalFragment = fragment.$internal.linkedFragments._fragno_internal;
+      internalFragment.withMiddleware(async ({ ifMatchesRoute }) => {
+        const result = await ifMatchesRoute("GET", "/status", async (_input, { json }) => {
+          return json({ ok: false, source: "internal-middleware" }, 418);
+        });
+
+        return result;
+      });
+
+      const response = await fragment.handler(
+        new Request("http://localhost/api/_internal/status", {
+          method: "GET",
+        }),
+      );
+
+      expect(response.status).toBe(418);
+      expect(await response.json()).toEqual({ ok: false, source: "internal-middleware" });
+    });
+
     it("should pass config and options to linked fragments", () => {
       interface Config {
         value: string;
@@ -1485,4 +1775,142 @@ describe("fragment-instantiator", () => {
       expect(data.code).toBe("INTERNAL_SERVER_ERROR");
     });
   });
+
+  describe("dry run mode", () => {
+    it("should handle dependency errors in dry run mode", () => {
+      interface Config {
+        requiredKey: string;
+      }
+
+      const definition = defineFragment<Config>("test-fragment")
+        .withDependencies(({ config }) => {
+          if (!config.requiredKey) {
+            throw new Error("Missing required key");
+          }
+          return { key: config.requiredKey };
+        })
+        .build();
+
+      // Without dry run - should throw
+      expect(() => {
+        instantiateFragment(definition, {} as Config, [], {});
+      }).toThrow("Missing required key");
+
+      // With dry run - should succeed with stub deps
+      const fragment = instantiateFragment(definition, {} as Config, [], {}, undefined, {
+        dryRun: true,
+      });
+
+      expect(fragment).toBeInstanceOf(FragnoInstantiatedFragment);
+      expect(fragment.$internal.deps).toEqual({});
+    });
+
+    it("should handle service errors in dry run mode", () => {
+      interface Config {
+        value: string;
+      }
+
+      const definition = defineFragment<Config>("test-fragment")
+        .withDependencies(({ config }) => {
+          if (!config.value) {
+            throw new Error("Missing value");
+          }
+          return { val: config.value };
+        })
+        .providesBaseService(({ deps }) => {
+          if (!deps.val) {
+            throw new Error("Missing deps.val");
+          }
+          return {
+            getValue: () => deps.val,
+          };
+        })
+        .build();
+
+      // Without dry run - should throw during deps initialization
+      expect(() => {
+        instantiateFragment(definition, {} as Config, [], {});
+      }).toThrow("Missing value");
+
+      // With dry run - should succeed with stub services
+      const fragment = instantiateFragment(definition, {} as Config, [], {}, undefined, {
+        dryRun: true,
+      });
+
+      expect(fragment).toBeInstanceOf(FragnoInstantiatedFragment);
+      // Services should be empty objects in dry run
+      expect(fragment.services).toBeDefined();
+    });
+
+    it("should handle named service errors in dry run mode", () => {
+      interface Config {
+        apiKey: string;
+      }
+
+      const definition = defineFragment<Config>("test-fragment")
+        .withDependencies(({ config }) => {
+          if (!config.apiKey) {
+            throw new Error("Missing API key");
+          }
+          return { key: config.apiKey };
+        })
+        .providesService("apiService", ({ deps }) => {
+          if (!deps.key) {
+            throw new Error("Cannot create service without key");
+          }
+          return {
+            call: () => `Calling with ${deps.key}`,
+          };
+        })
+        .build();
+
+      const fragment = instantiateFragment(definition, {} as Config, [], {}, undefined, {
+        dryRun: true,
+      });
+
+      expect(fragment).toBeInstanceOf(FragnoInstantiatedFragment);
+      expect(fragment.services.apiService).toBeDefined();
+      expect(fragment.services.apiService).toEqual({});
+    });
+
+    it("should handle private service errors in dry run mode", () => {
+      interface Config {
+        secret: string;
+      }
+
+      const definition = defineFragment<Config>("test-fragment")
+        .withDependencies(({ config }) => {
+          if (!config.secret) {
+            throw new Error("Missing secret");
+          }
+          return { secret: config.secret };
+        })
+        .build();
+
+      const fragment = instantiateFragment(definition, {} as Config, [], {}, undefined, {
+        dryRun: true,
+      });
+
+      expect(fragment).toBeInstanceOf(FragnoInstantiatedFragment);
+    });
+
+    it("should not catch errors when dry run is disabled", () => {
+      interface Config {
+        key: string;
+      }
+
+      const definition = defineFragment<Config>("test-fragment")
+        .withDependencies(({ config }) => {
+          if (!config.key) {
+            throw new Error("Missing key");
+          }
+          return { key: config.key };
+        })
+        .build();
+
+      expect(() => {
+        instantiateFragment(definition, {} as Config, [], {}, undefined, { dryRun: false });
+      }).toThrow("Missing key");
+    });
+  });
 });