@typed/app 1.0.0-beta.1

package/src/httpapiEndpointContract.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Unit tests for HttpApi endpoint contract validation.
+ * @see .docs/specs/httpapi-virtual-module-plugin/testing-strategy.md (endpoint contract validation)
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  validateEndpointContract,
+  type EndpointContractInput,
+} from "./internal/httpapiEndpointContract.js";
+
+describe("validateEndpointContract", () => {
+  const validContract: EndpointContractInput = {
+    route: { path: "/users", pathSchema: {}, querySchema: {} },
+    method: "GET",
+    handler: () => {},
+  };
+
+  it("accepts contract with all required fields and valid method", () => {
+    const result = validateEndpointContract(validContract);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.method).toBe("GET");
+      expect(result.value.route).toBe(validContract.route);
+      expect(result.value.handler).toBe(validContract.handler);
+    }
+  });
+
+  it("accepts all supported HTTP methods", () => {
+    const methods = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+    for (const method of methods) {
+      const result = validateEndpointContract({
+        ...validContract,
+        method,
+      });
+      expect(result.ok, `method ${method}`).toBe(true);
+      if (result.ok) expect(result.value.method).toBe(method);
+    }
+  });
+
+  it("rejects non-object input", () => {
+    expect(validateEndpointContract(null)).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract must be an object",
+      }
+    `);
+    expect(validateEndpointContract(undefined)).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract must be an object",
+      }
+    `);
+    expect(validateEndpointContract("string")).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract must be an object",
+      }
+    `);
+  });
+
+  it("rejects missing route", () => {
+    const { route: _, ...noRoute } = validContract as Record<string, unknown>;
+    expect(validateEndpointContract(noRoute)).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract missing required field: route",
+      }
+    `);
+  });
+
+  it("rejects missing method", () => {
+    const { method: _, ...noMethod } = validContract as Record<string, unknown>;
+    expect(validateEndpointContract(noMethod)).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract method: method must be a string",
+      }
+    `);
+  });
+
+  it("rejects invalid method", () => {
+    expect(
+      validateEndpointContract({ ...validContract, method: "INVALID" }),
+    ).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract method must be one of: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS",
+      }
+    `);
+  });
+
+  it("rejects empty string method", () => {
+    const result = validateEndpointContract({
+      ...validContract,
+      method: "  ",
+    });
+    expect(result.ok).toBe(false);
+  });
+
+  it("rejects route that is not an object", () => {
+    expect(
+      validateEndpointContract({ ...validContract, route: null }),
+    ).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract route must be an object (path + pathSchema + querySchema)",
+      }
+    `);
+  });
+
+  it("rejects route missing pathSchema", () => {
+    expect(
+      validateEndpointContract({
+        ...validContract,
+        route: { path: "/x", querySchema: {} },
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract route must include pathSchema",
+      }
+    `);
+  });
+
+  it("rejects route missing querySchema", () => {
+    expect(
+      validateEndpointContract({
+        ...validContract,
+        route: { path: "/x", pathSchema: {} },
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract route must include querySchema",
+      }
+    `);
+  });
+
+  it("rejects missing handler", () => {
+    const { handler: _, ...noHandler } = validContract as Record<string, unknown>;
+    expect(validateEndpointContract(noHandler)).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract missing required field: handler",
+      }
+    `);
+  });
+
+  it("rejects handler that is not a function", () => {
+    expect(
+      validateEndpointContract({ ...validContract, handler: "not a function" }),
+    ).toMatchInlineSnapshot(`
+      {
+        "ok": false,
+        "reason": "Endpoint contract handler must be a function",
+      }
+    `);
+  });
+});

package/src/httpapiFileRoles.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import {
+  classifyHttpApiFileRole,
+  compareHttpApiPathOrder,
+  HTTPAPI_DIRECTORY_COMPANION_FILES,
+  HTTPAPI_ENDPOINT_COMPANION_SUFFIXES,
+  isHttpApiScriptExtension,
+  normalizeHttpApiRelativePath,
+  sortHttpApiPaths,
+} from "./internal/httpapiFileRoles.js";
+
+describe("httpapiFileRoles", () => {
+  describe("normalizeHttpApiRelativePath", () => {
+    it("strips leading ./ and normalizes slashes", () => {
+      expect(normalizeHttpApiRelativePath("./users/list.ts")).toBe("users/list.ts");
+      expect(normalizeHttpApiRelativePath("users\\list.ts")).toBe("users/list.ts");
+    });
+  });
+
+  describe("isHttpApiScriptExtension", () => {
+    it("accepts .ts, .tsx, .js, .jsx, .mts, .cts, .mjs, .cjs", () => {
+      expect(isHttpApiScriptExtension(".ts")).toBe(true);
+      expect(isHttpApiScriptExtension(".TS")).toBe(true);
+      expect(isHttpApiScriptExtension(".js")).toBe(true);
+      expect(isHttpApiScriptExtension(".mts")).toBe(true);
+      expect(isHttpApiScriptExtension(".cjs")).toBe(true);
+    });
+    it("rejects .d.ts and others", () => {
+      expect(isHttpApiScriptExtension(".d.ts")).toBe(false);
+      expect(isHttpApiScriptExtension(".json")).toBe(false);
+    });
+  });
+
+  describe("classifyHttpApiFileRole", () => {
+    it("classifies _api.ts at root as api_root", () => {
+      const r = classifyHttpApiFileRole("_api.ts");
+      expect(r).toEqual({ role: "api_root", path: "_api.ts" });
+    });
+    it("classifies _api.ts in subdir as unsupported_reserved", () => {
+      const r = classifyHttpApiFileRole("users/_api.ts");
+      expect(r.role).toBe("unsupported_reserved");
+      expect("diagnosticCode" in r && r.diagnosticCode).toBe("HTTPAPI-ROLE-004");
+    });
+    it("classifies _group.ts as group_override", () => {
+      expect(classifyHttpApiFileRole("_group.ts")).toEqual({
+        role: "group_override",
+        path: "_group.ts",
+      });
+      expect(classifyHttpApiFileRole("users/_group.ts")).toEqual({
+        role: "group_override",
+        path: "users/_group.ts",
+      });
+    });
+    it("classifies directory companions", () => {
+      for (const f of HTTPAPI_DIRECTORY_COMPANION_FILES) {
+        const r = classifyHttpApiFileRole(`users/${f}`);
+        expect(r.role).toBe("directory_companion");
+        expect("kind" in r && r.kind).toBe(f);
+      }
+    });
+    it("classifies endpoint primary (no companion suffix)", () => {
+      const r = classifyHttpApiFileRole("users/list.ts");
+      expect(r).toEqual({ role: "endpoint_primary", path: "users/list.ts" });
+    });
+    it("classifies endpoint companions", () => {
+      for (const suffix of HTTPAPI_ENDPOINT_COMPANION_SUFFIXES) {
+        const r = classifyHttpApiFileRole(`users/list${suffix}.ts`);
+        expect(r.role).toBe("endpoint_companion");
+        expect("kind" in r && r.kind).toBe(suffix);
+        expect("endpointStem" in r && r.endpointStem).toBe("list");
+      }
+    });
+    it("rejects .d.ts as unsupported_reserved", () => {
+      const r = classifyHttpApiFileRole("list.d.ts");
+      expect(r.role).toBe("unsupported_reserved");
+      expect("diagnosticCode" in r && r.diagnosticCode).toBe("HTTPAPI-ROLE-001");
+    });
+    it("rejects underscore-prefixed non-matrix files as unsupported_reserved", () => {
+      const r = classifyHttpApiFileRole("_unknown.ts");
+      expect(r.role).toBe("unsupported_reserved");
+      expect("diagnosticCode" in r && r.diagnosticCode).toBe("HTTPAPI-ROLE-006");
+    });
+    it("rejects endpoint companion with empty base name", () => {
+      const r = classifyHttpApiFileRole(".openapi.ts");
+      expect(r.role).toBe("unsupported_reserved");
+    });
+  });
+
+  describe("sortHttpApiPaths / compareHttpApiPathOrder", () => {
+    it("sorts deterministically by normalized path", () => {
+      const paths = ["z/endpoint.ts", "a/endpoint.ts", "users/list.ts", "_api.ts"];
+      expect(sortHttpApiPaths(paths)).toEqual([
+        "_api.ts",
+        "a/endpoint.ts",
+        "users/list.ts",
+        "z/endpoint.ts",
+      ]);
+    });
+    it("compareHttpApiPathOrder is stable", () => {
+      expect(compareHttpApiPathOrder("a", "b")).toBeLessThan(0);
+      expect(compareHttpApiPathOrder("b", "a")).toBeGreaterThan(0);
+      expect(compareHttpApiPathOrder("a", "a")).toBe(0);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,40 @@
+export {
+  createRouterVirtualModulePlugin,
+  parseRouterVirtualModuleId,
+  resolveRouterTargetDirectory,
+  type ParseRouterVirtualModuleIdResult,
+  type ResolveRouterTargetDirectoryResult,
+  type RouterVirtualModulePluginOptions,
+} from "./RouterVirtualModulePlugin.js";
+export {
+  ROUTER_TYPE_TARGET_SPECS,
+  HTTPAPI_TYPE_TARGET_SPECS,
+} from "./internal/typeTargetSpecs.js";
+export {
+  createTypeInfoApiSessionForApp,
+  APP_TYPE_TARGET_BOOTSTRAP_CONTENT,
+} from "./createTypeInfoApiSessionForApp.js";
+
+export {
+  createHttpApiVirtualModulePlugin,
+  parseHttpApiVirtualModuleId,
+  resolveHttpApiTargetDirectory,
+  type HttpApiVirtualModulePluginOptions,
+  type ParseHttpApiVirtualModuleIdResult,
+  type ResolveHttpApiTargetDirectoryResult,
+} from "./HttpApiVirtualModulePlugin.js";
+export {
+  defineApiHandler,
+  emptyRecordString,
+  emptyRecordStringArray,
+  type ApiHandlerContext,
+  type ApiHandlerFn,
+  type ApiHandlerParams,
+  type ApiRoute,
+  type EndpointSchemas,
+  type HttpMethod,
+  type TypedApiHandler,
+} from "./httpapi/defineApiHandler.js";
+export { resolveConfig } from "./internal/resolveConfig.js";
+export type { AppConfig, RunConfig } from "./internal/appConfigTypes.js";
+export * from "./internal/appLayerTypes.js";

package/src/internal/appConfigTypes.ts

@@ -0,0 +1,12 @@
+import type * as Config from "effect/Config";
+
+/** Config for App (sync). disableListenLog matches HttpRouter.serve option. Use raw values. */
+export type AppConfig = {
+  readonly disableListenLog?: boolean;
+};
+
+/** Config for run(). Extends AppConfig; host/port may be raw or Config (yield* Config.*). Supply ConfigProvider.layer when using Config. */
+export type RunConfig = AppConfig & {
+  readonly host?: string | Config.Config<string>;
+  readonly port?: number | Config.Config<number>;
+};

package/src/internal/appLayerTypes.ts

@@ -0,0 +1,79 @@
+/**
+ * Type-safe Layer composition helpers for App/run.
+ * Uses Effect's Layer.Success, Layer.Error, Layer.Services, Layer.Any directly.
+ */
+import * as Layer from "effect/Layer";
+
+export type LayerAny = Layer.Layer<any, any, any> | Layer.Layer<never, any, any>;
+
+/** Single layer or non-empty array (uses Layer.mergeAll internally). */
+export type LayerOrGroup = LayerAny | readonly [LayerAny, ...ReadonlyArray<LayerAny>];
+
+function isLayerArray(l: LayerOrGroup): l is readonly [LayerAny, ...ReadonlyArray<LayerAny>] {
+  return Array.isArray(l) && l.length > 0;
+}
+
+function toLayer(l: LayerOrGroup): LayerAny {
+  if (isLayerArray(l)) {
+    const [first, ...rest] = l;
+    return Layer.mergeAll(first, ...rest);
+  }
+  return l;
+}
+
+/**
+ * Composes base layer with layers via provideMerge. Layers are provided TO the base.
+ * For precise output type, use ComposeWithLayers<Base, NormalizedLayers<Layers>>.
+ */
+export function composeWithLayers<
+  Base extends LayerAny,
+  const Layers extends ReadonlyArray<LayerOrGroup>,
+>(base: Base, layers: Layers): ComputeLayers<Layers, Base>;
+export function composeWithLayers<
+  Base extends LayerAny,
+  const Layers extends ReadonlyArray<LayerOrGroup>,
+>(base: Base, layers: Layers): LayerAny {
+  if (layers.length === 0) return base;
+  let out: LayerAny = base;
+  for (const layer of layers) {
+    out = Layer.provideMerge(out, toLayer(layer));
+  }
+
+  return out;
+}
+
+export type ComputeLayers<
+  Layers extends ReadonlyArray<LayerOrGroup>,
+  R extends LayerAny,
+> = readonly [] extends Layers
+  ? R
+  : Layers extends readonly [
+        infer Head extends LayerOrGroup,
+        ...infer Tail extends ReadonlyArray<LayerOrGroup>,
+      ]
+    ? ComputeLayers<Tail, ProvideMerge<R, ComputeLayer<Head>>>
+    : R;
+
+export type ProvideMerge<A extends LayerAny, B extends LayerAny> = Layer.Layer<
+  Layer.Success<A | B>,
+  Layer.Error<A | B>,
+  Exclude<Layer.Services<A>, Layer.Success<B>> | Layer.Services<B>
+  >;
+
+export type Provide<A extends LayerAny, B extends LayerAny> = Layer.Layer<
+  Layer.Success<A | B>,
+  Layer.Error<A | B>,
+  Exclude<Layer.Services<A>, Layer.Success<B>> | Layer.Services<B>
+>;
+
+type ComputeLayer<L extends LayerOrGroup> =
+  L extends Layer.Layer<infer A, infer E, infer R>
+    ? Layer.Layer<A, E, R>
+    : L extends ReadonlyArray<Layer.Layer<infer A, infer E, infer R>>
+      ? Layer.Layer<A, E, R>
+      : never;
+
+/** Normalizes LayerOrGroup to a single Layer at runtime. Arrays use Layer.mergeAll. */
+export function normalizeLayerInput<L extends LayerOrGroup>(input: L): LayerAny {
+  return toLayer(input);
+}