@controller-contract/server 0.1.1

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenny G Perez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index-CgtO_soW.d.mts

@@ -0,0 +1,40 @@
+import { OutputExit, OutputFail, OutputNext, OutputPass, ParamsFrom } from "@controller-contract/core";
+
+//#region src/utils/cast.d.ts
+declare namespace cast {
+  function params<T>(rawParams: T): ParamsFrom<string>;
+}
+//#endregion
+//#region src/utils/output.d.ts
+declare namespace output {
+  function next<T>(data: T, code?: number): OutputNext<T>;
+  function pass<T>(data: T, code?: number): OutputPass<T>;
+  function fail<const T extends string>(data: OutputFail<T>['data'], code?: number): OutputFail<T>;
+  /**
+   * Used to escape the controller contract state machine, useful for redirects.
+   */
+  function exit(): OutputExit;
+}
+declare function rootOnly(message: string): OutputFail<'root'>['data'];
+declare const StandardOutput: {
+  OK: OutputPass<{
+    key: "root";
+    message: string;
+  }[]>;
+  Created: OutputPass<{
+    key: "root";
+    message: string;
+  }[]>;
+  Accepted: OutputPass<{
+    key: "root";
+    message: string;
+  }[]>;
+  BadRequest: OutputFail<"root">;
+  Unauthorized: OutputFail<"root">;
+  Forbidden: OutputFail<"root">;
+  NotFound: OutputFail<"root">;
+  InternalServerError: OutputFail<"root">;
+  BadGateway: OutputFail<"root">;
+};
+//#endregion
+export { cast as i, output as n, rootOnly as r, StandardOutput as t };

package/dist/index.d.mts

@@ -0,0 +1,67 @@
+import { n as output } from "./index-CgtO_soW.mjs";
+import { ControllerContract, InputChannel, Method, NoInput, OutputFail, OutputMonads, ParamsFrom, Prettify } from "@controller-contract/core";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/types/builder-step.d.ts
+/**
+ * All the possible steps are defined below.
+ */
+declare namespace BuilderStep {
+  /**
+   * Always the first step
+   */
+  interface Endpoint<TContext> {
+    endpoint<const TMethod extends Method, const TPath extends string>(method: TMethod, path: TPath): BuilderStep.Output<TContext, TMethod, TPath, NoInput, never> & BuilderStep.Input<TContext, TMethod, TPath>;
+  }
+  interface Input<TContext, TMethod extends Method, TPath extends string> {
+    input<TInput>(channel: InputChannel, schema: StandardSchemaV1<TInput>): BuilderStep.Output<TContext, TMethod, TPath, TInput, OutputFail<Extract<keyof TInput, string>>>;
+  }
+  /**
+   * Always the last step
+   */
+  interface Output<TContext, TMethod extends Method, TPath extends string, TInput, TOutput extends OutputMonads> {
+    output<TFnOutput extends OutputMonads>(handler: OutputHandler<TContext, TPath, TInput, TFnOutput>): ControllerContract<TMethod, TPath, TInput, TOutput | TFnOutput>;
+  }
+}
+type OutputHandler<TContext, TPath extends string, TInput, TOutput extends OutputMonads> = (context: Prettify<TContext & {
+  params: ParamsFrom<TPath>;
+  input: TInput;
+  output: typeof output;
+}>) => TOutput | Promise<TOutput>;
+//#endregion
+//#region src/types/adapter.d.ts
+type AdaptorFn<TContext> = (blueprint: AdapterBlueprint<TContext> | AdapterWithSchemaBlueprint<TContext>) => void;
+declare class AdapterBlueprint<TContext> {
+  readonly method: Method;
+  readonly path: string;
+  readonly handler: OutputHandler<TContext, string, any, OutputMonads>;
+  constructor(method: Method, path: string, handler: OutputHandler<TContext, string, any, OutputMonads>);
+}
+declare class AdapterWithSchemaBlueprint<TContext> {
+  readonly method: Method;
+  readonly path: string;
+  readonly channel: InputChannel;
+  readonly schema: StandardSchemaV1;
+  readonly handler: OutputHandler<TContext, string, any, OutputMonads>;
+  constructor(method: Method, path: string, channel: InputChannel, schema: StandardSchemaV1, handler: OutputHandler<TContext, string, any, OutputMonads>);
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * This factory function provides the inteface for you to write the integration between
+ * `contract-controller` and your http library/framework of choice.
+ *
+ * When youre done writing your adaptor you can use the product in your code base.
+ *
+ * @example
+ * // lib/cc.ts
+ * export const cc = controllerContractFactory(() => {
+ *  // your code
+ * })
+ *
+ * // api/users.ts
+ * export const getUsers = cc.endpoint().input('...', ...).output(() => { ... });
+ */
+declare function controllerContractBuilderFactory<TContext>(adaptor: AdaptorFn<TContext>): BuilderStep.Endpoint<TContext>;
+//#endregion
+export { AdapterBlueprint, AdapterWithSchemaBlueprint, AdaptorFn, controllerContractBuilderFactory };

package/dist/index.mjs

@@ -0,0 +1,73 @@
+//#region src/types/adapter.ts
+var AdapterBlueprint = class {
+	method;
+	path;
+	handler;
+	constructor(method, path, handler) {
+		this.method = method;
+		this.path = path;
+		this.handler = handler;
+	}
+};
+var AdapterWithSchemaBlueprint = class {
+	method;
+	path;
+	channel;
+	schema;
+	handler;
+	constructor(method, path, channel, schema, handler) {
+		this.method = method;
+		this.path = path;
+		this.channel = channel;
+		this.schema = schema;
+		this.handler = handler;
+	}
+};
+//#endregion
+//#region src/steps/output.ts
+function outputStep(adaptor, method, path, channel, schema) {
+	return { output(handler) {
+		if (channel && schema) adaptor(new AdapterWithSchemaBlueprint(method, path, channel, schema, handler));
+		else adaptor(new AdapterBlueprint(method, path, handler));
+		return {};
+	} };
+}
+//#endregion
+//#region src/steps/input.ts
+function inputStep(adaptor, method, path) {
+	return { input(channel, schema) {
+		return outputStep(adaptor, method, path, channel, schema);
+	} };
+}
+//#endregion
+//#region src/steps/endpoint.ts
+function endpointStep(adaptor) {
+	return { endpoint(method, path) {
+		return {
+			...outputStep(adaptor, method, path),
+			...inputStep(adaptor, method, path)
+		};
+	} };
+}
+//#endregion
+//#region src/index.ts
+/**
+* This factory function provides the inteface for you to write the integration between
+* `contract-controller` and your http library/framework of choice.
+*
+* When youre done writing your adaptor you can use the product in your code base.
+*
+* @example
+* // lib/cc.ts
+* export const cc = controllerContractFactory(() => {
+*  // your code
+* })
+*
+* // api/users.ts
+* export const getUsers = cc.endpoint().input('...', ...).output(() => { ... });
+*/
+function controllerContractBuilderFactory(adaptor) {
+	return endpointStep(adaptor);
+}
+//#endregion
+export { AdapterBlueprint, AdapterWithSchemaBlueprint, controllerContractBuilderFactory };

package/dist/utils/index.d.mts

@@ -0,0 +1,2 @@
+import { i as cast, n as output, r as rootOnly, t as StandardOutput } from "../index-CgtO_soW.mjs";
+export { StandardOutput, cast, output, rootOnly };

package/dist/utils/index.mjs

@@ -0,0 +1,60 @@
+//#region src/utils/cast.ts
+let cast;
+(function(_cast) {
+	function params(rawParams) {
+		return rawParams;
+	}
+	_cast.params = params;
+})(cast || (cast = {}));
+//#endregion
+//#region src/utils/output.ts
+let output;
+(function(_output) {
+	function next(data, code = 100) {
+		return {
+			type: "next",
+			code,
+			data
+		};
+	}
+	_output.next = next;
+	function pass(data, code = 200) {
+		return {
+			type: "pass",
+			code,
+			data
+		};
+	}
+	_output.pass = pass;
+	function fail(data, code = 400) {
+		return {
+			type: "fail",
+			code,
+			data
+		};
+	}
+	_output.fail = fail;
+	function exit() {
+		return { type: "exit" };
+	}
+	_output.exit = exit;
+})(output || (output = {}));
+function rootOnly(message) {
+	return [{
+		key: "root",
+		message
+	}];
+}
+const StandardOutput = {
+	OK: output.pass(rootOnly("ok"), 200),
+	Created: output.pass(rootOnly("Created"), 201),
+	Accepted: output.pass(rootOnly("Accepted"), 202),
+	BadRequest: output.fail(rootOnly("Bad Request"), 400),
+	Unauthorized: output.fail(rootOnly("Unauthorized"), 401),
+	Forbidden: output.fail(rootOnly("Forbidden"), 403),
+	NotFound: output.fail(rootOnly("Not Found"), 404),
+	InternalServerError: output.fail(rootOnly("Internal Server Error"), 500),
+	BadGateway: output.fail(rootOnly("Bad Gateway"), 502)
+};
+//#endregion
+export { StandardOutput, cast, output, rootOnly };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@controller-contract/server",
+  "type": "module",
+  "version": "0.1.1",
+  "author": "kennychulo",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "package.json"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./utils": "./dist/utils/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.19",
+    "tsdown": "0.22.0",
+    "typescript": "6.0.3"
+  },
+  "dependencies": {
+    "@controller-contract/core": "0.1.1",
+    "@standard-schema/spec": "1.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "release": "pnpm publish"
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import { endpointStep } from './steps/endpoint';
+import type { AdaptorFn } from './types/adapter';
+
+export * from './types/adapter';
+
+/**
+ * This factory function provides the inteface for you to write the integration between
+ * `contract-controller` and your http library/framework of choice.
+ *
+ * When youre done writing your adaptor you can use the product in your code base.
+ *
+ * @example
+ * // lib/cc.ts
+ * export const cc = controllerContractFactory(() => {
+ *  // your code
+ * })
+ *
+ * // api/users.ts
+ * export const getUsers = cc.endpoint().input('...', ...).output(() => { ... });
+ */
+export function controllerContractBuilderFactory<TContext>(adaptor: AdaptorFn<TContext>) {
+  return endpointStep<TContext>(adaptor);
+}

package/src/steps/endpoint.ts

@@ -0,0 +1,15 @@
+import type { AdaptorFn } from '../types/adapter';
+import type { BuilderStep } from '../types/builder-step';
+import { inputStep } from './input';
+import { outputStep } from './output';
+
+export function endpointStep<TContext>(adaptor: AdaptorFn<TContext>): BuilderStep.Endpoint<TContext> {
+  return {
+    endpoint(method, path) {
+      return {
+        ...outputStep(adaptor, method, path),
+        ...inputStep(adaptor, method, path),
+      };
+    },
+  };
+}

package/src/steps/input.ts

@@ -0,0 +1,16 @@
+import type { Method } from '@controller-contract/core';
+import type { AdaptorFn } from '../types/adapter';
+import type { BuilderStep } from '../types/builder-step';
+import { outputStep } from './output';
+
+export function inputStep<TContext, const TMethod extends Method, const TPath extends string>(
+  adaptor: AdaptorFn<TContext>,
+  method: TMethod,
+  path: TPath,
+): BuilderStep.Input<TContext, TMethod, TPath> {
+  return {
+    input(channel, schema) {
+      return outputStep(adaptor, method, path, channel, schema);
+    },
+  };
+}

package/src/steps/output.ts

@@ -0,0 +1,30 @@
+import type { InputChannel, Method, OutputMonads } from '@controller-contract/core';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { AdapterBlueprint, AdapterWithSchemaBlueprint, type AdaptorFn } from '../types/adapter';
+import type { BuilderStep } from '../types/builder-step';
+
+export function outputStep<
+  TContext,
+  const TMethod extends Method,
+  const TPath extends string,
+  TInput,
+  TOutput extends OutputMonads,
+>(
+  adaptor: AdaptorFn<TContext>,
+  method: TMethod,
+  path: TPath,
+  channel?: InputChannel,
+  schema?: StandardSchemaV1<TInput>,
+): BuilderStep.Output<TContext, TMethod, TPath, TInput, TOutput> {
+  return {
+    output(handler) {
+      if (channel && schema) {
+        adaptor(new AdapterWithSchemaBlueprint(method, path, channel, schema, handler));
+      } else {
+        adaptor(new AdapterBlueprint(method, path, handler));
+      }
+
+      return {};
+    },
+  };
+}

package/src/types/adapter.ts

@@ -0,0 +1,25 @@
+import type { InputChannel, Method, OutputMonads } from '@controller-contract/core';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { OutputHandler } from './builder-step';
+
+export type AdaptorFn<TContext> = (
+  blueprint: AdapterBlueprint<TContext> | AdapterWithSchemaBlueprint<TContext>,
+) => void;
+
+export class AdapterBlueprint<TContext> {
+  constructor(
+    readonly method: Method,
+    readonly path: string,
+    readonly handler: OutputHandler<TContext, string, any, OutputMonads>,
+  ) {}
+}
+
+export class AdapterWithSchemaBlueprint<TContext> {
+  constructor(
+    readonly method: Method,
+    readonly path: string,
+    readonly channel: InputChannel,
+    readonly schema: StandardSchemaV1,
+    readonly handler: OutputHandler<TContext, string, any, OutputMonads>,
+  ) {}
+}

package/src/types/builder-step.ts

@@ -0,0 +1,59 @@
+import type {
+  ControllerContract,
+  InputChannel,
+  Method,
+  NoInput,
+  OutputFail,
+  OutputMonads,
+  ParamsFrom,
+  Prettify,
+} from '@controller-contract/core';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { output } from '../utils';
+
+/**
+ * All the possible steps are defined below.
+ */
+export namespace BuilderStep {
+  /**
+   * Always the first step
+   */
+  export interface Endpoint<TContext> {
+    endpoint<const TMethod extends Method, const TPath extends string>(
+      method: TMethod,
+      path: TPath,
+    ): BuilderStep.Output<TContext, TMethod, TPath, NoInput, never> & BuilderStep.Input<TContext, TMethod, TPath>;
+  }
+
+  export interface Input<TContext, TMethod extends Method, TPath extends string> {
+    input<TInput>(
+      channel: InputChannel,
+      schema: StandardSchemaV1<TInput>,
+    ): BuilderStep.Output<TContext, TMethod, TPath, TInput, OutputFail<Extract<keyof TInput, string>>>;
+  }
+
+  /**
+   * Always the last step
+   */
+  export interface Output<
+    TContext,
+    TMethod extends Method,
+    TPath extends string,
+    TInput,
+    TOutput extends OutputMonads,
+  > {
+    output<TFnOutput extends OutputMonads>(
+      handler: OutputHandler<TContext, TPath, TInput, TFnOutput>,
+    ): ControllerContract<TMethod, TPath, TInput, TOutput | TFnOutput>;
+  }
+}
+
+export type OutputHandler<TContext, TPath extends string, TInput, TOutput extends OutputMonads> = (
+  context: Prettify<
+    TContext & {
+      params: ParamsFrom<TPath>;
+      input: TInput;
+      output: typeof output;
+    }
+  >,
+) => TOutput | Promise<TOutput>;

package/src/utils/cast.ts

@@ -0,0 +1,7 @@
+import type { ParamsFrom } from '@controller-contract/core';
+
+export namespace cast {
+  export function params<T>(rawParams: T) {
+    return rawParams as ParamsFrom<string>;
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './cast';
+export * from './output';

package/src/utils/output.ts

@@ -0,0 +1,55 @@
+import type { OutputExit, OutputFail, OutputNext, OutputPass } from '@controller-contract/core';
+
+export namespace output {
+  export function next<T>(data: T, code = 100): OutputNext<T> {
+    return {
+      type: 'next',
+      code,
+      data,
+    };
+  }
+
+  export function pass<T>(data: T, code = 200): OutputPass<T> {
+    return {
+      type: 'pass',
+      code,
+      data,
+    };
+  }
+
+  export function fail<const T extends string>(data: OutputFail<T>['data'], code = 400): OutputFail<T> {
+    return {
+      type: 'fail',
+      code,
+      data,
+    };
+  }
+
+  /**
+   * Used to escape the controller contract state machine, useful for redirects.
+   */
+  export function exit(): OutputExit {
+    return {
+      type: 'exit',
+    };
+  }
+}
+
+export function rootOnly(message: string): OutputFail<'root'>['data'] {
+  return [{ key: 'root', message }];
+}
+
+export const StandardOutput = {
+  // 200
+  OK: output.pass(rootOnly('ok'), 200),
+  Created: output.pass(rootOnly('Created'), 201),
+  Accepted: output.pass(rootOnly('Accepted'), 202),
+  // 400
+  BadRequest: output.fail(rootOnly('Bad Request'), 400),
+  Unauthorized: output.fail(rootOnly('Unauthorized'), 401),
+  Forbidden: output.fail(rootOnly('Forbidden'), 403),
+  NotFound: output.fail(rootOnly('Not Found'), 404),
+  // 500
+  InternalServerError: output.fail(rootOnly('Internal Server Error'), 500),
+  BadGateway: output.fail(rootOnly('Bad Gateway'), 502),
+};