Ekklesia/packages/module-sdk/tests/define-module-runtime.test.ts

import { describe, expect, expectTypeOf, it, vi } from "vitest";
import {
  defineModuleRuntime,
  EMPTY_MODULE_CONFIGURATION,
  isModuleHttpMethod,
  MODULE_HTTP_METHODS,
  type ModuleHttpRouteRegistrar,
  type ModuleRegistrationContext,
  type ModuleRuntimeDefinitionWithDatabase,
  type ModuleRuntimeDefinitionWithoutDatabase,
} from "../src/index.js";

describe("defineModuleRuntime", () => {
  it("types the ABI executor for a database module, and no database at all otherwise", () => {
    defineModuleRuntime({
      database: { abi: 1 },
      id: "example",
      version: "0.1.0",
      start({ services }) {
        expectTypeOf(services.database.query).toBeFunction();
        expectTypeOf(services.database.abiVersion).toEqualTypeOf<1>();
        // @ts-expect-error ABI-v1 modules never receive the legacy Drizzle facade.
        services.database.select();
      },
      register({ http }) {
        http.route({
          handler: (_request, { services }) => {
            expectTypeOf(services.database.abiVersion).toEqualTypeOf<1>();
            return new Response();
          },
          maxBodyBytes: 0,
          method: "GET",
          path: "/",
          permission: "example.read",
        });
      },
    });

    defineModuleRuntime({
      id: "no-database",
      version: "0.1.0",
      start({ services }) {
        // The SDK never types the legacy Drizzle facade (ADR 0053): a module without the ABI has
        // no database to reach.
        expectTypeOf(services.database).toBeNever();
      },
    });
  });

  it("types the result as the SDK's own named interfaces, so a module's declarations can name it", () => {
    // A module that emits declarations names its default export's type; with an inferred literal
    // type that would reach into packages a standalone module does not depend on directly.
    expectTypeOf(
      defineModuleRuntime({ database: { abi: 1 }, id: "example", version: "0.1.0" }),
    ).toEqualTypeOf<ModuleRuntimeDefinitionWithDatabase>();
    expectTypeOf(
      defineModuleRuntime({ id: "example", version: "0.1.0" }),
    ).toEqualTypeOf<ModuleRuntimeDefinitionWithoutDatabase>();
  });

  it("defines a frozen server runtime without duplicating the static manifest", async () => {
    const start = vi.fn();
    const runtime = defineModuleRuntime({
      id: "example",
      start,
      version: "0.1.0",
    });

    expect(runtime).toEqual({ id: "example", start, version: "0.1.0" });
    expect(Object.isFrozen(runtime)).toBe(true);
  });

  it("rejects invalid runtime definitions", () => {
    expect(() =>
      defineModuleRuntime({
        id: "Not Valid",
        version: "0.1.0",
      }),
    ).toThrow("Invalid Ekklesia module runtime definition.");
  });

  it("re-exports the module-http contract so a module's register hook can declare routes", async () => {
    expect(MODULE_HTTP_METHODS).toContain("GET");
    expect(isModuleHttpMethod("GET")).toBe(true);
    expect(isModuleHttpMethod("get")).toBe(false);

    const registeredRoutes: unknown[] = [];
    const http: ModuleHttpRouteRegistrar = {
      route: (definition) => {
        registeredRoutes.push(definition);
      },
    };
    const runtime = defineModuleRuntime({
      id: "example",
      version: "0.1.0",
      register({ http: registrar }) {
        registrar.route({
          method: "GET",
          path: "/records",
          permission: "example.records.read",
          maxBodyBytes: 0,
          handler: () => new Response(null, { status: 204 }),
        });
      },
    });

    const context: ModuleRegistrationContext = {
      capabilities: {
        provide: () => undefined,
        resolve: () => undefined,
      },
      // A module declaring no configuration still receives an empty snapshot rather than
      // `undefined`, so module code never branches on whether the platform supplied one.
      config: EMPTY_MODULE_CONFIGURATION,
      http,
      moduleId: "example",
      realtime: { channel: () => undefined },
    };
    await runtime.register?.(context);

    expect(registeredRoutes).toHaveLength(1);
    expect(registeredRoutes[0]).toMatchObject({ method: "GET", path: "/records" });
  });
});