@jlnstack/procedure 0.0.1

package/src/next.ts

@@ -0,0 +1,161 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import { init as coreInit, type InitOptions } from "./core";
+import {
+  createMiddleware,
+  createProcedureBuilder,
+  type InferMiddlewareArrayInput,
+  type InferMiddlewareArrayOutput,
+  type InferMiddlewareOutput,
+  type InternalMiddleware,
+  type MergeInput,
+  type Middleware,
+  type ProcedureBuilderFactory,
+  type Run,
+} from "./core-internal";
+import type { Prettify } from "./types";
+
+type ExtractParams<TInput> = TInput extends { params: infer P } ? P : never;
+
+interface NextProcedureBuilder<TContext, TInput = {}> {
+  use<TInputExt, TMiddleware extends Middleware<TInputExt, TContext, any>>(
+    middleware: TMiddleware,
+  ): NextProcedureBuilder<
+    InferMiddlewareOutput<TMiddleware>,
+    MergeInput<TInput, TInputExt>
+  >;
+
+  use<TMiddlewares extends readonly Middleware<any, TContext, any>[]>(
+    middlewares: [...TMiddlewares],
+  ): NextProcedureBuilder<
+    InferMiddlewareArrayOutput<TMiddlewares>,
+    MergeInput<TInput, InferMiddlewareArrayInput<TMiddlewares>>
+  >;
+
+  input<TSchema extends StandardSchemaV1>(
+    schema: TSchema,
+  ): NextProcedureBuilder<
+    TContext,
+    TInput & StandardSchemaV1.InferInput<TSchema>
+  >;
+
+  params<T, TSchema extends StandardSchemaV1 | undefined = undefined>(
+    schema?: TSchema,
+  ): NextProcedureBuilder<
+    Prettify<
+      TContext & {
+        params: TSchema extends StandardSchemaV1
+          ? StandardSchemaV1.InferOutput<TSchema>
+          : T;
+      }
+    >,
+    Prettify<
+      TInput & {
+        params: Promise<
+          TSchema extends StandardSchemaV1
+            ? StandardSchemaV1.InferOutput<TSchema>
+            : T
+        >;
+      }
+    >
+  >;
+
+  searchParams<TSchema extends StandardSchemaV1>(
+    schema: TSchema,
+  ): NextProcedureBuilder<
+    Prettify<
+      TContext & { searchParams: StandardSchemaV1.InferOutput<TSchema> }
+    >,
+    Prettify<
+      TInput & {
+        searchParams: Promise<Record<string, string | string[] | undefined>>;
+      }
+    >
+  >;
+
+  run: Run<TContext, TInput>;
+  page: Run<
+    TContext,
+    Prettify<
+      TInput & {
+        searchParams: Promise<Record<string, string | string[] | undefined>>;
+        params: Promise<{ [key: string]: string }>;
+      }
+    >,
+    ReactNode
+  >;
+  rsc: Run<TContext, TInput, ReactNode>;
+  metadata: Run<TContext, TInput, Metadata>;
+  layout: Run<TContext, TInput & { children: ReactNode }, ReactNode>;
+  layoutMetadata: Run<
+    Prettify<Omit<TContext, "searchParams">>,
+    Prettify<Omit<TInput, "searchParams">>,
+    Metadata
+  >;
+
+  staticParams: Run<TContext, TInput, ExtractParams<TContext>[]>;
+}
+
+const createNextBuilder: ProcedureBuilderFactory = (
+  middlewares: InternalMiddleware[],
+  factory?: ProcedureBuilderFactory,
+) => {
+  const core = createProcedureBuilder(
+    middlewares,
+    factory ?? createNextBuilder,
+  );
+
+  return {
+    ...core,
+
+    params() {
+      const mw = createMiddleware(
+        "NEXT_PARAMS",
+        async ({ input, ctx, next }: any) => {
+          const params = await input.params;
+
+          return next({ ctx: { ...ctx, params } });
+        },
+      );
+      return createNextBuilder([...middlewares, mw], factory) as any;
+    },
+
+    searchParams(schema: StandardSchemaV1) {
+      const mw = createMiddleware(
+        "NEXT_SEARCH_PARAMS",
+        async ({ input, ctx, next }: any) => {
+          const searchParams = await input.searchParams;
+
+          const result = await schema["~standard"].validate(searchParams);
+          if (result.issues) throw new Error("Invalid search params");
+          return next({ ctx: { ...ctx, searchParams: result.value } });
+        },
+      );
+      return createNextBuilder([...middlewares, mw], factory) as any;
+    },
+
+    page: core.run,
+    rsc: core.run,
+    metadata: core.run,
+    layout: core.run,
+    layoutMetadata: core.run,
+    staticParams: core.run,
+  } as any;
+};
+
+export const init = <TContext>(options: InitOptions<TContext>) => {
+  const core = coreInit(options);
+  const initialMiddlewares: InternalMiddleware[] = [
+    createMiddleware("INITIAL_CONTEXT", async ({ next }: any) => {
+      return next({ ctx: await options.ctx() });
+    }),
+  ];
+
+  return {
+    middleware: core.middleware,
+    procedure: createNextBuilder(
+      initialMiddlewares,
+    ) as unknown as NextProcedureBuilder<TContext>,
+  };
+};

package/src/react.ts

@@ -0,0 +1,66 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { ReactNode } from "react";
+import { init as coreInit, type InitOptions } from "./core";
+import {
+  createMiddleware,
+  createProcedureBuilder,
+  type InferMiddlewareOutput,
+  type InternalMiddleware,
+  type MergeInput,
+  type Middleware,
+  type ProcedureBuilderFactory,
+  type Run,
+} from "./core-internal";
+
+interface ReactProcedureBuilder<TContext, TInput = Record<string, never>> {
+  use<TInputExt, TMiddleware extends Middleware<TInputExt, TContext, any>>(
+    middleware: TMiddleware,
+  ): ReactProcedureBuilder<
+    InferMiddlewareOutput<TMiddleware>,
+    MergeInput<TInput, TInputExt>
+  >;
+
+  input<TSchema extends StandardSchemaV1>(
+    schema: TSchema,
+  ): ReactProcedureBuilder<
+    TContext,
+    MergeInput<TInput, StandardSchemaV1.InferInput<TSchema>>
+  >;
+
+  run: Run<TContext, TInput>;
+  rsc: Run<TContext, TInput, ReactNode>;
+  serverFn: Run<TContext, TInput>;
+}
+
+const createReactBuilder: ProcedureBuilderFactory = (
+  middlewares: InternalMiddleware[],
+  factory?: ProcedureBuilderFactory,
+) => {
+  const core = createProcedureBuilder(
+    middlewares,
+    factory ?? createReactBuilder,
+  );
+
+  return {
+    ...core,
+    rsc: core.run,
+    serverFn: core.run,
+  };
+};
+
+export const init = <TContext>(options: InitOptions<TContext>) => {
+  const core = coreInit(options);
+  const initialMiddlewares: InternalMiddleware[] = [
+    createMiddleware("INITIAL_CONTEXT", async ({ next }: any) => {
+      return next({ ctx: await options.ctx() });
+    }),
+  ];
+
+  return {
+    middleware: core.middleware,
+    procedure: createReactBuilder(initialMiddlewares) as ReactProcedureBuilder<
+      TContext,
+      Record<string, never>
+    >,
+  };
+};

package/src/types.ts

@@ -0,0 +1,4 @@
+export type Prettify<T> = { [K in keyof T]: T[K] } & {};
+export type Awaitable<T> = T | Promise<T>;
+
+export type IsEmptyObject<T> = T extends Record<string, never> ? true : false;

package/test/core.test-d.ts

@@ -0,0 +1,89 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { expectTypeOf, test } from "vitest";
+import { init } from "../src/core";
+import type { Middleware } from "../src/core-internal";
+
+const createSchema = <T>(): StandardSchemaV1<T> =>
+  ({
+    "~standard": {
+      version: 1,
+      vendor: "test",
+      validate: () => ({ value: {} as T }),
+    },
+  }) as StandardSchemaV1<T>;
+
+const factory = init({ ctx: () => ({ userId: "123" }) });
+
+test("init - context propagates to procedure", () => {
+  factory.procedure.run(({ ctx }) => {
+    expectTypeOf(ctx).toEqualTypeOf<{ userId: string }>();
+  });
+});
+
+test("use - single middleware updates context", () => {
+  const mw: Middleware<
+    unknown,
+    { userId: string },
+    { role: "admin" | "user" }
+  > = ({ next }) => next({ ctx: { role: "admin" } });
+
+  factory.procedure.use(mw).run(({ ctx }) => {
+    expectTypeOf(ctx).toEqualTypeOf<{ role: "admin" | "user" }>();
+  });
+});
+
+test("use - array of middlewares merges contexts", () => {
+  const mw1: Middleware<unknown, { userId: string }, { a: number }> = ({
+    next,
+  }) => next({ ctx: { a: 1 } });
+  const mw2: Middleware<unknown, { userId: string }, { b: string }> = ({
+    next,
+  }) => next({ ctx: { b: "hello" } });
+
+  factory.procedure.use([mw1, mw2]).run(({ ctx }) => {
+    expectTypeOf(ctx).toEqualTypeOf<{ a: number; b: string }>();
+  });
+});
+
+test("input - schema type added to input", () => {
+  const schema = createSchema<{ name: string }>();
+
+  factory.procedure.input(schema).run(({ input }) => {
+    expectTypeOf(input).toEqualTypeOf<{ name: string }>();
+  });
+});
+
+test("run - without input returns no-arg function", () => {
+  const fn = factory.procedure.run(() => "result");
+  expectTypeOf(fn).toEqualTypeOf<() => Promise<string>>();
+});
+
+test("run - with input returns function with arg", () => {
+  const schema = createSchema<{ id: number }>();
+  const fn = factory.procedure.input(schema).run(({ input }) => input.id);
+  expectTypeOf(fn).toEqualTypeOf<(input: { id: number }) => Promise<number>>();
+});
+
+test("run - with partial input returns function with optional arg", () => {
+  const schema = createSchema<{ id?: number }>();
+  const fn = factory.procedure.input(schema).run(() => "result");
+  expectTypeOf(fn).toEqualTypeOf<
+    (input?: { id?: number }) => Promise<string>
+  >();
+});
+
+test("middleware factory - preserves types", () => {
+  const mw = factory.middleware(({ ctx, input, next }) => {
+    expectTypeOf(ctx).toEqualTypeOf<{ userId: string }>();
+    expectTypeOf(input).toEqualTypeOf<unknown>();
+    return next({ ctx: { role: "admin" as const } });
+  });
+
+  expectTypeOf(mw).toEqualTypeOf<
+    Middleware<unknown, { userId: string }, { role: "admin" }>
+  >();
+
+  factory.procedure.use(mw).run(({ ctx }) => {
+    expectTypeOf(ctx).toEqualTypeOf<{ role: "admin" }>();
+  });
+});

package/test/core.test.ts

@@ -0,0 +1,57 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { describe, expect, it } from "vitest";
+import { init } from "../src/core";
+
+const createSchema = <T>(): StandardSchemaV1<T> =>
+  ({
+    "~standard": {
+      version: 1,
+      vendor: "test",
+      validate: (value: unknown) => ({ value: value as T }),
+    },
+  }) as StandardSchemaV1<T>;
+
+const factory = init({ ctx: () => ({ userId: "123" }) });
+
+describe("init", () => {
+  it("provides initial context", async () => {
+    const fn = factory.procedure.run(({ ctx }) => ctx.userId);
+    expect(await fn()).toBe("123");
+  });
+});
+
+describe("use", () => {
+  it("single middleware extends context", async () => {
+    const fn = factory.procedure
+      .use(({ next }) => next({ ctx: { role: "admin" } }))
+      .run(({ ctx }) => ctx.role);
+
+    expect(await fn()).toBe("admin");
+  });
+
+  it("array of middlewares merges contexts", async () => {
+    const fn = factory.procedure
+      .use([
+        ({ next }) => next({ ctx: { a: 1 } }),
+        ({ next }) => next({ ctx: { b: 2 } }),
+      ])
+      .run(({ ctx }) => ctx.a + ctx.b);
+
+    expect(await fn()).toBe(3);
+  });
+});
+
+describe("input", () => {
+  it("passes input to run function", async () => {
+    const schema = createSchema<{ x: number }>();
+    const fn = factory.procedure.input(schema).run(({ input }) => input.x * 2);
+    expect(await fn({ x: 5 })).toBe(10);
+  });
+});
+
+describe("run", () => {
+  it("returns the result", async () => {
+    const fn = factory.procedure.run(() => "hello");
+    expect(await fn()).toBe("hello");
+  });
+});

package/test/next.test-d.ts

@@ -0,0 +1,177 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import { expectTypeOf, test } from "vitest";
+import { init } from "../src/next";
+
+const createSchema = <T>(): StandardSchemaV1<T> =>
+  ({
+    "~standard": {
+      version: 1,
+      vendor: "test",
+      validate: () => ({ value: {} as T }),
+    },
+  }) as StandardSchemaV1<T>;
+
+const factory = init({ ctx: () => ({ userId: "123" }) });
+
+test("init - context propagates to procedure", () => {
+  factory.procedure.run(({ ctx }) => {
+    expectTypeOf(ctx).toEqualTypeOf<{ userId: string }>();
+  });
+});
+
+test("params - adds params to context without schema", () => {
+  factory.procedure.params<{ slug: string }>().run(({ ctx, input }) => {
+    expectTypeOf(ctx).toExtend<{ userId: string; params: { slug: string } }>();
+    return input;
+  });
+});
+
+test("params - adds params to context with schema", () => {
+  const schema = createSchema<{ id: number }>();
+
+  factory.procedure
+    .params<{ id: number }, typeof schema>(schema)
+    .run(({ ctx }) => {
+      expectTypeOf(ctx).toExtend<{ userId: string; params: { id: number } }>();
+    });
+});
+
+test("params - input requires Promise<params>", () => {
+  const fn = factory.procedure
+    .params<{ slug: string }>()
+    .run(({ ctx }) => ctx.params.slug);
+
+  expectTypeOf(fn).toEqualTypeOf<
+    (input: { params: Promise<{ slug: string }> }) => Promise<string>
+  >();
+});
+
+test("searchParams - adds validated searchParams to context", () => {
+  const schema = createSchema<{ page: number; limit: number }>();
+
+  factory.procedure.searchParams(schema).run(({ ctx, input }) => {
+    expectTypeOf(ctx).toExtend<{
+      userId: string;
+      searchParams: { page: number; limit: number };
+    }>();
+    return input;
+  });
+});
+
+test("searchParams - input requires Promise<Record<string, ...>>", () => {
+  const schema = createSchema<{ q: string }>();
+  const fn = factory.procedure
+    .searchParams(schema)
+    .run(({ ctx }) => ctx.searchParams.q);
+
+  expectTypeOf(fn).toEqualTypeOf<
+    (input: {
+      searchParams: Promise<Record<string, string | string[] | undefined>>;
+    }) => Promise<string>
+  >();
+});
+
+test("page - returns ReactNode and accepts page props", () => {
+  const fn = factory.procedure.page(() => null as ReactNode);
+
+  expectTypeOf(fn).toBeFunction();
+});
+
+test("page - context available in page handler", () => {
+  factory.procedure.page(({ ctx }) => {
+    expectTypeOf(ctx).toEqualTypeOf<{ userId: string }>();
+    return null;
+  });
+});
+
+test("rsc - returns ReactNode", () => {
+  const fn = factory.procedure.rsc(() => null as ReactNode);
+
+  expectTypeOf(fn).toBeFunction();
+});
+
+test("metadata - returns Metadata type", () => {
+  const fn = factory.procedure.metadata(() => ({ title: "Test" }));
+
+  expectTypeOf(fn).toBeFunction();
+  expectTypeOf(fn).returns.resolves.toExtend<Metadata>();
+});
+
+test("layout - receives children in input", () => {
+  factory.procedure.layout(({ input }) => {
+    expectTypeOf(input).toEqualTypeOf<{ children: ReactNode }>();
+    return null;
+  });
+});
+
+test("layout - function signature", () => {
+  const fn = factory.procedure.layout(() => null as ReactNode);
+
+  expectTypeOf(fn).toBeFunction();
+});
+
+test("layoutMetadata - excludes searchParams from context", () => {
+  const searchSchema = createSchema<{ q: string }>();
+
+  factory.procedure.searchParams(searchSchema).layoutMetadata(({ ctx }) => {
+    expectTypeOf(ctx).toEqualTypeOf<{ userId: string }>();
+    return { title: "Layout" };
+  });
+});
+
+test("staticParams - returns array of params", () => {
+  const fn = factory.procedure
+    .params<{ slug: string }>()
+    .staticParams(() => [{ slug: "a" }, { slug: "b" }]);
+
+  type ParamsArray = { slug: string }[];
+  expectTypeOf(fn).returns.resolves.toEqualTypeOf<ParamsArray>();
+});
+
+test("chaining params and searchParams", () => {
+  const paramsSchema = createSchema<{ id: string }>();
+  const searchSchema = createSchema<{ tab: string }>();
+
+  factory.procedure
+    .params<{ id: string }, typeof paramsSchema>(paramsSchema)
+    .searchParams(searchSchema)
+    .page(({ ctx }) => {
+      expectTypeOf(ctx).toExtend<{
+        userId: string;
+        params: { id: string };
+        searchParams: { tab: string };
+      }>();
+      return null;
+    });
+});
+
+test("middleware preserves input requirements through chain", () => {
+  const mw = factory.middleware(({ next }) =>
+    next({ ctx: { role: "admin" as const } }),
+  );
+
+  factory.procedure
+    .use(mw)
+    .params<{ slug: string }>()
+    .page(({ ctx }) => {
+      expectTypeOf(ctx).toExtend<{ role: "admin"; params: { slug: string } }>();
+      return null;
+    });
+});
+
+test("middleware chain - function signature with middleware and params", () => {
+  const mw = factory.middleware(({ next }) =>
+    next({ ctx: { role: "admin" as const } }),
+  );
+
+  const fn = factory.procedure
+    .use(mw)
+    .params<{ slug: string }>()
+    .run(({ ctx }) => ctx.params.slug);
+
+  expectTypeOf(fn).toEqualTypeOf<
+    (input: { params: Promise<{ slug: string }> }) => Promise<string>
+  >();
+});