feat(rpc): add defineService and the immutable procedure builder

packages/rpc/src/contract.ts

@@ -0,0 +1,66 @@
+import type { ObjectSchema } from "@wrnexus/validation";
+import type { AnyProcedures, InferInput, ProcedureDef, ServiceContract } from "./types.ts";
+
+/** A service name lands in a URL path, so keep it unescaped-safe. */
+const SAFE_SERVICE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A procedure name is also a property the caller writes as client.doThing(). */
+const SAFE_PROCEDURE = /^[a-z][a-zA-Z0-9]*$/;
+
+/**
+ * Fluent, IMMUTABLE builder: every method returns a new builder, so a shared
+ * base can be branched without one branch mutating another.
+ */
+export class ProcedureBuilder<Input, Output> {
+  private constructor(private readonly def: ProcedureDef<Input, Output>) {}
+
+  static create(): ProcedureBuilder<void, void> {
+    return new ProcedureBuilder<void, void>({});
+  }
+
+  input<S extends ObjectSchema<object>>(schema: S): ProcedureBuilder<InferInput<S>, Output> {
+    return new ProcedureBuilder<InferInput<S>, Output>({
+      ...this.def,
+      input: schema,
+    } as ProcedureDef<InferInput<S>, Output>);
+  }
+
+  output<T>(): ProcedureBuilder<Input, T> {
+    return new ProcedureBuilder<Input, T>({ ...this.def } as ProcedureDef<Input, T>);
+  }
+
+  permission(id: string): ProcedureBuilder<Input, Output> {
+    return new ProcedureBuilder<Input, Output>({ ...this.def, permission: id });
+  }
+
+  /** Mark safe to retry. Anything not marked is never retried. */
+  idempotent(): ProcedureBuilder<Input, Output> {
+    return new ProcedureBuilder<Input, Output>({ ...this.def, idempotent: true });
+  }
+
+  build(): ProcedureDef<Input, Output> {
+    return Object.freeze({ ...this.def });
+  }
+}
+
+export const procedure = ProcedureBuilder.create();
+
+export function defineService<Procedures extends AnyProcedures>(def: {
+  name: string;
+  procedures: Procedures;
+}): ServiceContract<Procedures> {
+  if (!SAFE_SERVICE.test(def.name)) {
+    throw new Error(
+      `WRN-RPC-CONTRACT: service name ${JSON.stringify(def.name)} must be lowercase ` +
+        `alphanumeric with single hyphens, e.g. "billing" or "billing-v2".`,
+    );
+  }
+  for (const name of Object.keys(def.procedures)) {
+    if (!SAFE_PROCEDURE.test(name)) {
+      throw new Error(
+        `WRN-RPC-CONTRACT: procedure name ${JSON.stringify(name)} on service ` +
+          `'${def.name}' must be a lowercase-initial identifier, e.g. "createInvoice".`,
+      );
+    }
+  }
+  return Object.freeze({ name: def.name, procedures: Object.freeze({ ...def.procedures }) });
+}

packages/rpc/src/index.ts

@@ -20,3 +20,5 @@ export type {
 
 export { RPC_ERROR_CODES, ServiceError, failure, isRetryableStatus, success } from "./errors.ts";
 export type { RpcErrorCode, ToResultOptions } from "./errors.ts";
+
+export { defineService, procedure, ProcedureBuilder } from "./contract.ts";