dabke 0.78.0

package/src/client.schemas.ts

@@ -0,0 +1,163 @@
+/**
+ * Zod schemas for CP-SAT solver transport types.
+ *
+ * These schemas define the contract between scheduling clients and the solver service.
+ * TypeScript types are derived from these schemas using z.infer to ensure they stay in sync.
+ *
+ * @see client.types.ts for the derived TypeScript types
+ */
+
+import { z } from "zod";
+
+// --------------------------------------------------------------------------
+// Variable schemas
+// --------------------------------------------------------------------------
+
+export const SolverTermSchema = z.object({
+  var: z.string(),
+  coeff: z.number(),
+});
+
+export const BoolVariableSchema = z.object({
+  type: z.literal("bool"),
+  name: z.string(),
+});
+
+export const IntVariableSchema = z.object({
+  type: z.literal("int"),
+  name: z.string(),
+  min: z.number(),
+  max: z.number(),
+});
+
+export const IntervalVariableSchema = z.object({
+  type: z.literal("interval"),
+  name: z.string(),
+  start: z.number(),
+  end: z.number(),
+  size: z.number(),
+  /** If present, this is an optional interval enforced by this boolean var. */
+  presenceVar: z.string().optional(),
+});
+
+export const SolverVariableSchema = z.union([
+  BoolVariableSchema,
+  IntVariableSchema,
+  IntervalVariableSchema,
+]);
+
+// --------------------------------------------------------------------------
+// Constraint schemas
+// --------------------------------------------------------------------------
+
+export const LinearConstraintSchema = z.object({
+  type: z.literal("linear"),
+  terms: z.array(SolverTermSchema),
+  op: z.union([z.literal("<="), z.literal(">="), z.literal("==")]),
+  rhs: z.number(),
+});
+
+export const SoftLinearConstraintSchema = z.object({
+  type: z.literal("soft_linear"),
+  terms: z.array(SolverTermSchema),
+  op: z.union([z.literal("<="), z.literal(">=")]),
+  rhs: z.number(),
+  penalty: z.number(),
+  id: z.string().optional(),
+});
+
+export const ExactlyOneConstraintSchema = z.object({
+  type: z.literal("exactly_one"),
+  vars: z.array(z.string()),
+});
+
+export const AtMostOneConstraintSchema = z.object({
+  type: z.literal("at_most_one"),
+  vars: z.array(z.string()),
+});
+
+export const ImplicationConstraintSchema = z.object({
+  type: z.literal("implication"),
+  if: z.string(),
+  // oxlint-disable-next-line unicorn/no-thenable -- This is a schema property, not a Promise
+  then: z.string(),
+});
+
+export const BoolOrConstraintSchema = z.object({
+  type: z.literal("bool_or"),
+  vars: z.array(z.string()),
+});
+
+export const BoolAndConstraintSchema = z.object({
+  type: z.literal("bool_and"),
+  vars: z.array(z.string()),
+});
+
+export const NoOverlapConstraintSchema = z.object({
+  type: z.literal("no_overlap"),
+  intervals: z.array(z.string()),
+});
+
+export const SolverConstraintSchema = z.union([
+  LinearConstraintSchema,
+  SoftLinearConstraintSchema,
+  ExactlyOneConstraintSchema,
+  AtMostOneConstraintSchema,
+  ImplicationConstraintSchema,
+  BoolOrConstraintSchema,
+  BoolAndConstraintSchema,
+  NoOverlapConstraintSchema,
+]);
+
+// --------------------------------------------------------------------------
+// Objective schema
+// --------------------------------------------------------------------------
+
+export const SolverObjectiveSchema = z.object({
+  sense: z.union([z.literal("minimize"), z.literal("maximize")]),
+  terms: z.array(SolverTermSchema),
+});
+
+// --------------------------------------------------------------------------
+// Options schema
+// --------------------------------------------------------------------------
+
+export const SolverOptionsSchema = z.object({
+  timeLimitSeconds: z.number().optional(),
+  solutionLimit: z.number().optional(),
+});
+
+// --------------------------------------------------------------------------
+// Request/Response schemas
+// --------------------------------------------------------------------------
+
+export const SolverRequestSchema = z.object({
+  variables: z.array(SolverVariableSchema),
+  constraints: z.array(SolverConstraintSchema),
+  objective: SolverObjectiveSchema.optional(),
+  options: SolverOptionsSchema.optional(),
+});
+
+export const SolverStatusSchema = z.enum(["OPTIMAL", "FEASIBLE", "INFEASIBLE", "TIMEOUT", "ERROR"]);
+
+export const SolverStatisticsSchema = z.object({
+  solveTimeMs: z.number().optional(),
+  conflicts: z.number().optional(),
+  branches: z.number().optional(),
+});
+
+export const SoftConstraintViolationSchema = z.object({
+  constraintId: z.string(),
+  violationAmount: z.number(),
+  targetValue: z.number(),
+  actualValue: z.number(),
+});
+
+export const SolverResponseSchema = z.object({
+  status: SolverStatusSchema,
+  values: z.record(z.string(), z.number()).optional(),
+  statistics: SolverStatisticsSchema.optional(),
+  error: z.string().optional(),
+  solutionInfo: z.string().optional(),
+  softViolations: z.array(SoftConstraintViolationSchema).optional(),
+});

package/src/client.ts

@@ -0,0 +1,67 @@
+import {
+  type FetcherLike,
+  type SolverClient,
+  type SolverRequest,
+  type SolverResponse,
+} from "./client.types.js";
+
+export type {
+  SolverClient,
+  SolverRequest,
+  SolverResponse,
+  SolverVariable,
+  SolverConstraint,
+  SolverTerm,
+  SolverObjective,
+  FetcherLike,
+} from "./client.types.js";
+
+const normalizeFetch = (
+  fetcher: FetcherLike,
+): ((input: string | URL, init?: RequestInit) => Promise<Response>) => {
+  if (typeof fetcher === "function") return fetcher;
+  return fetcher.fetch.bind(fetcher);
+};
+
+/**
+ * Generic HTTP client for the solver service.
+ */
+export class HttpSolverClient implements SolverClient {
+  #fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+  #baseUrl: string;
+
+  constructor(fetcher: FetcherLike, baseUrl: string = "http://localhost:8080") {
+    this.#fetch = normalizeFetch(fetcher);
+    this.#baseUrl = baseUrl.replace(/\/$/, "");
+  }
+
+  async solve(request: SolverRequest, options?: { signal?: AbortSignal }): Promise<SolverResponse> {
+    const res = await this.#fetch(`${this.#baseUrl}/solve`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(request),
+      signal: options?.signal,
+    });
+
+    const bodyText = await res.text();
+    if (!res.ok) {
+      const detail = bodyText ? `: ${bodyText}` : "";
+      throw new Error(`Solver returned ${res.status}${detail}`);
+    }
+
+    if (!bodyText) {
+      throw new Error("Solver returned an empty response");
+    }
+
+    return JSON.parse(bodyText) as SolverResponse;
+  }
+
+  async health(): Promise<void> {
+    const res = await this.#fetch(`${this.#baseUrl}/health`);
+    if (!res.ok) {
+      const detail = await res.text().catch(() => "");
+      const suffix = detail ? `: ${detail}` : "";
+      throw new Error(`Solver health check failed with ${res.status}${suffix}`);
+    }
+  }
+}

package/src/client.types.ts

@@ -0,0 +1,66 @@
+/**
+ * CP-SAT solver transport types and status constants.
+ *
+ * Types are derived from Zod schemas to ensure validation and types stay in sync.
+ *
+ * @see client.schemas.ts for the source Zod schemas
+ */
+
+import type { z } from "zod";
+import type {
+  SolverTermSchema,
+  SolverVariableSchema,
+  SolverConstraintSchema,
+  SolverObjectiveSchema,
+  SolverRequestSchema,
+  SolverResponseSchema,
+  SolverStatusSchema,
+  SoftConstraintViolationSchema,
+} from "./client.schemas.js";
+
+// --------------------------------------------------------------------------
+// Types derived from Zod schemas
+// --------------------------------------------------------------------------
+
+export type SolverTerm = z.infer<typeof SolverTermSchema>;
+
+export type SolverVariable = z.infer<typeof SolverVariableSchema>;
+
+export type SolverConstraint = z.infer<typeof SolverConstraintSchema>;
+
+export type SolverObjective = z.infer<typeof SolverObjectiveSchema>;
+
+export type SolverRequest = z.infer<typeof SolverRequestSchema>;
+
+export type SolverResponse = z.infer<typeof SolverResponseSchema>;
+
+export type SolverStatus = z.infer<typeof SolverStatusSchema>;
+
+export type SoftConstraintViolation = z.infer<typeof SoftConstraintViolationSchema>;
+
+// --------------------------------------------------------------------------
+// Status constants (for convenience)
+// --------------------------------------------------------------------------
+
+export const SOLVER_STATUS = {
+  OPTIMAL: "OPTIMAL",
+  FEASIBLE: "FEASIBLE",
+  INFEASIBLE: "INFEASIBLE",
+  TIMEOUT: "TIMEOUT",
+  ERROR: "ERROR",
+} as const;
+
+// --------------------------------------------------------------------------
+// Client interface
+// --------------------------------------------------------------------------
+
+export type FetcherLike =
+  | typeof fetch
+  | {
+      fetch: typeof fetch;
+    };
+
+export interface SolverClient {
+  solve(request: SolverRequest, options?: { signal?: AbortSignal }): Promise<SolverResponse>;
+  health?(): Promise<void>;
+}