@fragno-dev/core 0.1.6 → 0.1.8

package/src/client/client.ts

@@ -1,6 +1,6 @@
 import { nanoquery, type FetcherStore, type MutatorStore } from "@nanostores/query";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import { task, type ReadableAtom, type Store } from "nanostores";
+import { computed, task, type ReadableAtom, type Store } from "nanostores";
 import type { FragnoRouteConfig, HTTPMethod, NonGetHTTPMethod } from "../api/api";
 import {
   buildPath,
@@ -252,11 +252,11 @@ export type FragnoClientHookData<
   >;
   query(args?: {
     path?: MaybeExtractPathParamsOrWiden<TPath, string>;
-    query?: Record<TQueryParameters, string>;
+    query?: Record<TQueryParameters, string | undefined>;
   }): Promise<StandardSchemaV1.InferOutput<TOutputSchema>>;
   store(args?: {
     path?: MaybeExtractPathParamsOrWiden<TPath, string | ReadableAtom<string>>;
-    query?: Record<TQueryParameters, string | ReadableAtom<string>>;
+    query?: Record<TQueryParameters, string | undefined | ReadableAtom<string | undefined>>;
   }): FetcherStore<StandardSchemaV1.InferOutput<TOutputSchema>, FragnoClientError<TErrorCode>>;
   [GET_HOOK_SYMBOL]: true;
 } & {
@@ -287,14 +287,14 @@ export type FragnoClientMutatorData<
   mutateQuery(args?: {
     body?: InferOr<TInputSchema, undefined>;
     path?: MaybeExtractPathParamsOrWiden<TPath, string>;
-    query?: Record<TQueryParameters, string>;
+    query?: Record<TQueryParameters, string | undefined>;
   }): Promise<InferOr<TOutputSchema, undefined>>;
 
   mutatorStore: MutatorStore<
     {
       body?: InferOr<TInputSchema, undefined>;
       path?: MaybeExtractPathParamsOrWiden<TPath, string | ReadableAtom<string>>;
-      query?: Record<TQueryParameters, string | ReadableAtom<string>>;
+      query?: Record<TQueryParameters, string | undefined | ReadableAtom<string | undefined>>;
     },
     InferOr<TOutputSchema, undefined>,
     FragnoClientError<TErrorCode>
@@ -313,7 +313,7 @@ export function buildUrl<TPath extends string>(
   },
   params: {
     pathParams?: Record<string, string | ReadableAtom<string>>;
-    queryParams?: Record<string, string | ReadableAtom<string>>;
+    queryParams?: Record<string, string | undefined | ReadableAtom<string | undefined>>;
   },
 ): string {
   const { baseUrl = "", mountRoute, path } = config;
@@ -322,7 +322,12 @@ export function buildUrl<TPath extends string>(
   const normalizedPathParams = unwrapObject(pathParams) as ExtractPathParams<TPath, string>;
   const normalizedQueryParams = unwrapObject(queryParams) ?? {};
 
-  const searchParams = new URLSearchParams(normalizedQueryParams);
+  // Filter out undefined values to prevent URLSearchParams from converting them to string "undefined"
+  const filteredQueryParams = Object.fromEntries(
+    Object.entries(normalizedQueryParams).filter(([_, value]) => value !== undefined),
+  ) as Record<string, string>;
+
+  const searchParams = new URLSearchParams(filteredQueryParams);
   const builtPath = buildPath(path, normalizedPathParams ?? {});
   const search = searchParams.toString() ? `?${searchParams.toString()}` : "";
   return `${baseUrl}${mountRoute}${builtPath}${search}`;
@@ -333,6 +338,7 @@ export function buildUrl<TPath extends string>(
  *
  * The returned array is always: path, pathParams (In order they appear in the path), queryParams (In alphabetical order)
  * Missing pathParams are replaced with "<missing>".
+ * Atoms with undefined values are wrapped in computed atoms that map undefined to "" to avoid nanoquery treating the key as incomplete.
  * @param path
  * @param params
  * @returns
@@ -342,7 +348,7 @@ export function getCacheKey<TMethod extends HTTPMethod, TPath extends string>(
   path: TPath,
   params?: {
     pathParams?: Record<string, string | ReadableAtom<string>>;
-    queryParams?: Record<string, string | ReadableAtom<string>>;
+    queryParams?: Record<string, string | undefined | ReadableAtom<string | undefined>>;
   },
 ): (string | ReadableAtom<string>)[] {
   if (!params) {
@@ -357,7 +363,15 @@ export function getCacheKey<TMethod extends HTTPMethod, TPath extends string>(
   const queryParamValues = queryParams
     ? Object.keys(queryParams)
         .sort()
-        .map((key) => queryParams[key])
+        .map((key) => {
+          const value = queryParams[key];
+          // If it's an atom, wrap it to convert undefined to ""
+          if (value && typeof value === "object" && "get" in value) {
+            return computed(value as ReadableAtom<string | undefined>, (v) => v ?? "");
+          }
+          // Plain string value (or undefined)
+          return value ?? "";
+        })
     : [];
 
   return [method, path, ...pathParamValues, ...queryParamValues];
@@ -668,14 +682,19 @@ export class ClientBuilder<
 
     async function callServerSideHandler(params: {
       pathParams?: Record<string, string | ReadableAtom<string>>;
-      queryParams?: Record<string, string | ReadableAtom<string>>;
+      queryParams?: Record<string, string | undefined | ReadableAtom<string | undefined>>;
     }): Promise<Response> {
       const { pathParams, queryParams } = params ?? {};
 
       const normalizedPathParams = unwrapObject(pathParams) as ExtractPathParams<TPath, string>;
       const normalizedQueryParams = unwrapObject(queryParams) ?? {};
 
-      const searchParams = new URLSearchParams(normalizedQueryParams);
+      // Filter out undefined values to prevent URLSearchParams from converting them to string "undefined"
+      const filteredQueryParams = Object.fromEntries(
+        Object.entries(normalizedQueryParams).filter(([_, value]) => value !== undefined),
+      ) as Record<string, string>;
+
+      const searchParams = new URLSearchParams(filteredQueryParams);
 
       const result = await route.handler(
         RequestInputContext.fromSSRContext({
@@ -692,7 +711,7 @@ export class ClientBuilder<
 
     async function executeQuery(params?: {
       pathParams?: Record<string, string | ReadableAtom<string>>;
-      queryParams?: Record<string, string | ReadableAtom<string>>;
+      queryParams?: Record<string, string | undefined | ReadableAtom<string | undefined>>;
     }): Promise<Response> {
       const { pathParams, queryParams } = params ?? {};
 

package/src/mod.ts

@@ -1,7 +1,14 @@
-export { defineFragment, FragmentBuilder, type FragmentDefinition } from "./api/fragment-builder";
+export {
+  defineFragment,
+  FragmentBuilder,
+  type FragmentDefinition,
+  type RouteHandler,
+} from "./api/fragment-builder";
 
 export {
   createFragment,
+  instantiateFragment,
+  FragmentInstantiationBuilder,
   type FragnoFragmentSharedConfig,
   type FragnoPublicConfig,
   type FragnoPublicClientConfig,
@@ -18,3 +25,6 @@ export {
   type AnyRouteOrFactory,
   type FlattenRouteFactories,
 } from "./api/route";
+
+export { RequestInputContext } from "./api/request-input-context";
+export { RequestOutputContext } from "./api/request-output-context";

package/src/test/test.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, expectTypeOf } from "vitest";
+import { describe, it, expect, expectTypeOf, assert } from "vitest";
 import { createFragmentForTest } from "./test";
 import { defineFragment } from "../api/fragment-builder";
 import { defineRoute, defineRoutes } from "../api/route";
@@ -46,9 +46,11 @@ describe("createFragmentForTest", () => {
       .withDependencies(({ config }) => ({
         client: { apiKey: config.apiKey },
       }))
-      .withServices(({ deps }) => ({
-        getApiKey: () => deps.client.apiKey,
-      }));
+      .providesService(({ deps, defineService }) =>
+        defineService({
+          getApiKey: () => deps.client.apiKey,
+        }),
+      );
 
     const testFragment = createFragmentForTest(fragment, [], {
       config: { apiKey: "test-key" },
@@ -62,9 +64,11 @@ describe("createFragmentForTest", () => {
       .withDependencies(({ config }) => ({
         client: { apiKey: config.apiKey },
       }))
-      .withServices(({ deps }) => ({
-        getApiKey: () => deps.client.apiKey,
-      }));
+      .providesService(({ deps, defineService }) =>
+        defineService({
+          getApiKey: () => deps.client.apiKey,
+        }),
+      );
 
     const testFragment = createFragmentForTest(fragment, [], {
       config: { apiKey: "test-key" },
@@ -81,9 +85,11 @@ describe("createFragmentForTest", () => {
 
     const fragment = defineFragment<Config>("test")
       .withDependencies(() => ({ dep: "value" }))
-      .withServices(({ config }) => ({
-        multiply: (x: number) => x * config.multiplier,
-      }));
+      .providesService(({ config, defineService }) =>
+        defineService({
+          multiply: (x: number) => x * config.multiplier,
+        }),
+      );
 
     const routeFactory = defineRoutes<Config, Deps, Services>().create(({ services }) => [
       defineRoute({
@@ -233,7 +239,7 @@ describe("fragment.callRoute", () => {
   });
 
   it("should handle route factory created with defineRoutes", async () => {
-    const fragment = defineFragment<{ apiKey: string }>("test").withServices(() => ({
+    const fragment = defineFragment<{ apiKey: string }>("test").providesService(() => ({
       getGreeting: (name: string) => `Hello, ${name}!`,
       getCount: () => 42,
     }));
@@ -270,10 +276,9 @@ describe("fragment.callRoute", () => {
       pathParams: { name: "World" },
     });
 
-    expect(greetingResponse.type).toBe("json");
-    if (greetingResponse.type === "json") {
-      expect(greetingResponse.data).toEqual({ message: "Hello, World!" });
-    }
+    console.log(greetingResponse);
+    assert(greetingResponse.type === "json");
+    expect(greetingResponse.data).toEqual({ message: "Hello, World!" });
 
     // Test second route
     const countResponse = await testFragment.callRoute("GET", "/count");

package/src/test/test.ts

@@ -23,12 +23,14 @@ export interface CreateFragmentForTestOptions<
   TServices,
   TAdditionalContext extends Record<string, unknown>,
   TOptions extends FragnoPublicConfig,
+  TRequiredInterfaces extends Record<string, unknown> = {},
 > {
   config: TConfig;
   options?: Partial<TOptions>;
   deps?: Partial<TDeps>;
   services?: Partial<TServices>;
   additionalContext?: Partial<TAdditionalContext>;
+  interfaceImplementations?: TRequiredInterfaces;
 }
 
 /**
@@ -108,18 +110,34 @@ export function createFragmentForTest<
   TServices extends Record<string, unknown>,
   TAdditionalContext extends Record<string, unknown>,
   TOptions extends FragnoPublicConfig,
+  TRequiredInterfaces extends Record<string, unknown>,
+  TProvidedInterfaces extends Record<string, unknown>,
   const TRoutesOrFactories extends readonly AnyRouteOrFactory[],
 >(
   fragmentBuilder: {
-    definition: FragmentDefinition<TConfig, TDeps, TServices, TAdditionalContext>;
+    definition: FragmentDefinition<
+      TConfig,
+      TDeps,
+      TServices,
+      TAdditionalContext,
+      TRequiredInterfaces,
+      TProvidedInterfaces
+    >;
     $requiredOptions: TOptions;
   },
   routesOrFactories: TRoutesOrFactories,
-  options: CreateFragmentForTestOptions<TConfig, TDeps, TServices, TAdditionalContext, TOptions>,
+  options: CreateFragmentForTestOptions<
+    TConfig,
+    TDeps,
+    TServices,
+    TAdditionalContext,
+    TOptions,
+    TRequiredInterfaces
+  >,
 ): FragmentForTest<
   TConfig,
-  TDeps,
-  TServices,
+  TDeps & TRequiredInterfaces,
+  TServices & TProvidedInterfaces,
   TAdditionalContext,
   TOptions,
   FlattenRouteFactories<TRoutesOrFactories>
@@ -130,6 +148,7 @@ export function createFragmentForTest<
     deps: depsOverride,
     services: servicesOverride,
     additionalContext: additionalContextOverride,
+    interfaceImplementations,
   } = options;
 
   // Create deps from definition or use empty object
@@ -138,16 +157,30 @@ export function createFragmentForTest<
     ? definition.dependencies(config, fragmentOptions)
     : ({} as TDeps);
 
-  // Merge deps with overrides
-  const deps = { ...baseDeps, ...depsOverride } as TDeps;
+  // Merge deps with overrides and interface implementations
+  const deps = {
+    ...baseDeps,
+    ...interfaceImplementations,
+    ...depsOverride,
+  } as TDeps & TRequiredInterfaces;
 
   // Create services from definition or use empty object
   const baseServices = definition.services
     ? definition.services(config, fragmentOptions, deps)
     : ({} as TServices);
 
-  // Merge services with overrides
-  const services = { ...baseServices, ...servicesOverride } as TServices;
+  // Handle providedServices - can be either a factory function or a direct object
+  const providedServicesResolved =
+    typeof definition.providedServices === "function"
+      ? definition.providedServices(config, fragmentOptions, deps)
+      : definition.providedServices;
+
+  // Merge services with provided services and overrides
+  const services = {
+    ...baseServices,
+    ...providedServicesResolved,
+    ...servicesOverride,
+  } as TServices & TProvidedInterfaces;
 
   // Merge additional context with options
   const additionalContext = {
@@ -157,7 +190,13 @@ export function createFragmentForTest<
   } as TAdditionalContext & TOptions;
 
   // Create the actual fragment using createFragment
-  const fragment = createFragment(fragmentBuilder, config, routesOrFactories, fragmentOptions);
+  const fragment = createFragment(
+    fragmentBuilder,
+    config,
+    routesOrFactories,
+    fragmentOptions,
+    interfaceImplementations,
+  );
 
   return {
     config,