@procedures/client 0.0.0-stage → 0.1.0

package/src/procedures/core/logic.ts

@@ -0,0 +1,225 @@
+/**
+ * Logic Operators
+ *
+ * Unified logic operators with group theory annotations.
+ *
+ * Operator Properties:
+ * - **Arity**: unary (1 input) or variadic (n inputs)
+ * - **Commutativity**: whether order affects the result
+ * - **Short-circuit**: whether evaluation stops early
+ *
+ * | Operator | Arity    | Commutative | Short-circuit |
+ * |----------|----------|-------------|---------------|
+ * | and      | variadic | yes*        | yes (first falsy) |
+ * | or       | variadic | yes*        | yes (first truthy) |
+ * | not      | unary    | n/a         | no |
+ * | all      | variadic | yes         | yes (first falsy) |
+ * | any      | variadic | yes         | yes (first truthy) |
+ *
+ * *Note: and/or are commutative for boolean results but the returned
+ * value may differ based on order (returns the short-circuiting value).
+ */
+
+// =============================================================================
+// Logic Metadata
+// =============================================================================
+
+/**
+ * Metadata for logic operators, including algebraic properties.
+ * Extends ProcedureMetadata with logic-specific fields.
+ */
+export interface LogicMetadata {
+  description: string;
+  tags: string[];
+  /** Number of inputs: 'unary' (1) or 'variadic' (n) */
+  arity: 'unary' | 'variadic';
+  /** Whether the operation is commutative (order-independent for result) */
+  commutative: boolean;
+  /** Whether the operation short-circuits */
+  shortCircuit: boolean;
+  /** Index signature for compatibility with ProcedureMetadata */
+  [key: string]: unknown;
+}
+
+// =============================================================================
+// Logic Operator Factories
+// =============================================================================
+
+/**
+ * Create a variadic logic operator handler.
+ *
+ * @param shortCircuitOn - Predicate that triggers short-circuit return
+ * @returns Handler function for the logic operator
+ *
+ * @example
+ * ```typescript
+ * // AND: short-circuit on first falsy value
+ * const andHandler = variadicLogic(v => !v);
+ *
+ * // OR: short-circuit on first truthy value
+ * const orHandler = variadicLogic(v => !!v);
+ * ```
+ */
+export function variadicLogic(
+  shortCircuitOn: (value: unknown) => boolean
+): (input: { values: unknown[] }) => Promise<unknown> {
+  return async (input: { values: unknown[] }): Promise<unknown> => {
+    const { values } = input;
+
+    for (const value of values) {
+      if (shortCircuitOn(value)) {
+        return value; // Short-circuit return
+      }
+    }
+
+    // Return last value if no short-circuit triggered
+    return values[values.length - 1];
+  };
+}
+
+/**
+ * Create a unary logic operator handler.
+ *
+ * @param transform - Transformation function for the value
+ * @returns Handler function for the logic operator
+ *
+ * @example
+ * ```typescript
+ * // NOT: negate the value
+ * const notHandler = unaryLogic(v => !v);
+ *
+ * // Boolean coercion
+ * const boolHandler = unaryLogic(v => !!v);
+ * ```
+ */
+export function unaryLogic<T>(
+  transform: (value: unknown) => T
+): (input: { value: unknown }) => Promise<T> {
+  return async (input: { value: unknown }): Promise<T> => {
+    return transform(input.value);
+  };
+}
+
+// =============================================================================
+// Pre-built Handlers
+// =============================================================================
+
+/**
+ * Handler type for variadic logic operators.
+ */
+export type VariadicLogicHandler = (input: { values: unknown[] }) => Promise<unknown>;
+
+/**
+ * Handler type for unary logic operators.
+ */
+export type UnaryLogicHandler = (input: { value: unknown }) => Promise<boolean>;
+
+/**
+ * AND handler - returns first falsy or last value.
+ * Short-circuits on falsy.
+ */
+export const andHandler: VariadicLogicHandler = variadicLogic(v => !v);
+
+/**
+ * OR handler - returns first truthy or last value.
+ * Short-circuits on truthy.
+ */
+export const orHandler: VariadicLogicHandler = variadicLogic(v => !!v);
+
+/**
+ * NOT handler - returns boolean negation.
+ */
+export const notHandler: UnaryLogicHandler = unaryLogic(v => !v);
+
+/**
+ * ALL handler - alias for AND with boolean result.
+ * Returns true if all values are truthy.
+ */
+export const allHandler = async (input: { values: unknown[] }): Promise<boolean> => {
+  return input.values.every(v => !!v);
+};
+
+/**
+ * ANY handler - alias for OR with boolean result.
+ * Returns true if any value is truthy.
+ */
+export const anyHandler = async (input: { values: unknown[] }): Promise<boolean> => {
+  return input.values.some(v => !!v);
+};
+
+/**
+ * NONE handler - returns true if all values are falsy.
+ */
+export const noneHandler = async (input: { values: unknown[] }): Promise<boolean> => {
+  return input.values.every(v => !v);
+};
+
+// =============================================================================
+// Metadata Definitions
+// =============================================================================
+
+/**
+ * Metadata for the AND operator.
+ */
+export const andMetadata: LogicMetadata = {
+  description: "Short-circuit AND (returns first falsy or last value)",
+  tags: ["core", "logic"],
+  arity: "variadic",
+  commutative: true,
+  shortCircuit: true,
+};
+
+/**
+ * Metadata for the OR operator.
+ */
+export const orMetadata: LogicMetadata = {
+  description: "Short-circuit OR (returns first truthy or last value)",
+  tags: ["core", "logic"],
+  arity: "variadic",
+  commutative: true,
+  shortCircuit: true,
+};
+
+/**
+ * Metadata for the NOT operator.
+ */
+export const notMetadata: LogicMetadata = {
+  description: "Logical NOT",
+  tags: ["core", "logic"],
+  arity: "unary",
+  commutative: false, // n/a for unary
+  shortCircuit: false,
+};
+
+/**
+ * Metadata for the ALL operator.
+ */
+export const allMetadata: LogicMetadata = {
+  description: "Returns true if all values are truthy",
+  tags: ["core", "logic"],
+  arity: "variadic",
+  commutative: true,
+  shortCircuit: true,
+};
+
+/**
+ * Metadata for the ANY operator.
+ */
+export const anyMetadata: LogicMetadata = {
+  description: "Returns true if any value is truthy",
+  tags: ["core", "logic"],
+  arity: "variadic",
+  commutative: true,
+  shortCircuit: true,
+};
+
+/**
+ * Metadata for the NONE operator.
+ */
+export const noneMetadata: LogicMetadata = {
+  description: "Returns true if all values are falsy",
+  tags: ["core", "logic"],
+  arity: "variadic",
+  commutative: true,
+  shortCircuit: true,
+};

package/src/procedures/core/math.ts

@@ -0,0 +1,469 @@
+/**
+ * Math Procedures
+ *
+ * Arithmetic and mathematical operations for procedure aggregation.
+ * All procedures are namespaced under "client" (e.g., client.add, client.multiply).
+ */
+
+import { z } from "zod";
+import { numberOutput } from "./outputs.js";
+import { defineProcedure, namespace } from "../define.js";
+import type { AnyProcedure, Procedure } from "../types.js";
+
+// =============================================================================
+// Add Procedure
+// =============================================================================
+
+interface AddInput {
+  a: number;
+  b: number;
+}
+
+const AddInputSchema = z.object({
+  a: z.number().describe("The first operand"),
+  b: z.number().describe("The second operand"),
+});
+
+type AddProcedure = Procedure<AddInput, number, { description: string; tags: string[] }>;
+
+const addProcedure: AddProcedure = defineProcedure({
+  path: ["add"],
+  input: AddInputSchema,
+  output: numberOutput("The sum of a and b"),
+  metadata: {
+    description: "Add two numbers",
+    tags: ["core", "math"],
+  },
+  handler: async (input: AddInput): Promise<number> => {
+    return input.a + input.b;
+  },
+});
+
+// =============================================================================
+// Subtract Procedure
+// =============================================================================
+
+interface SubtractInput {
+  a: number;
+  b: number;
+}
+
+const SubtractInputSchema = z.object({
+  a: z.number().describe("The first operand"),
+  b: z.number().describe("The second operand"),
+});
+
+type SubtractProcedure = Procedure<SubtractInput, number, { description: string; tags: string[] }>;
+
+const subtractProcedure: SubtractProcedure = defineProcedure({
+  path: ["subtract"],
+  input: SubtractInputSchema,
+  output: numberOutput("a minus b"),
+  metadata: {
+    description: "Subtract b from a",
+    tags: ["core", "math"],
+  },
+  handler: async (input: SubtractInput): Promise<number> => {
+    return input.a - input.b;
+  },
+});
+
+// =============================================================================
+// Multiply Procedure
+// =============================================================================
+
+interface MultiplyInput {
+  a: number;
+  b: number;
+}
+
+const MultiplyInputSchema = z.object({
+  a: z.number().describe("The first operand"),
+  b: z.number().describe("The second operand"),
+});
+
+type MultiplyProcedure = Procedure<MultiplyInput, number, { description: string; tags: string[] }>;
+
+const multiplyProcedure: MultiplyProcedure = defineProcedure({
+  path: ["multiply"],
+  input: MultiplyInputSchema,
+  output: numberOutput("The product of a and b"),
+  metadata: {
+    description: "Multiply two numbers",
+    tags: ["core", "math"],
+  },
+  handler: async (input: MultiplyInput): Promise<number> => {
+    return input.a * input.b;
+  },
+});
+
+// =============================================================================
+// Divide Procedure
+// =============================================================================
+
+interface DivideInput {
+  a: number;
+  b: number;
+}
+
+const DivideInputSchema = z.object({
+  a: z.number().describe("The first operand"),
+  b: z.number().describe("The second operand"),
+});
+
+type DivideProcedure = Procedure<DivideInput, number, { description: string; tags: string[] }>;
+
+const divideProcedure: DivideProcedure = defineProcedure({
+  path: ["divide"],
+  input: DivideInputSchema,
+  output: numberOutput("a divided by b"),
+  metadata: {
+    description: "Divide a by b",
+    tags: ["core", "math"],
+  },
+  handler: async (input: DivideInput): Promise<number> => {
+    if (input.b === 0) {
+      throw new Error("Division by zero");
+    }
+    return input.a / input.b;
+  },
+});
+
+// =============================================================================
+// Mod Procedure
+// =============================================================================
+
+interface ModInput {
+  a: number;
+  b: number;
+}
+
+const ModInputSchema = z.object({
+  a: z.number().describe("The first operand"),
+  b: z.number().describe("The second operand"),
+});
+
+type ModProcedure = Procedure<ModInput, number, { description: string; tags: string[] }>;
+
+const modProcedure: ModProcedure = defineProcedure({
+  path: ["mod"],
+  input: ModInputSchema,
+  output: numberOutput("The remainder of a divided by b"),
+  metadata: {
+    description: "Modulo (remainder of a / b)",
+    tags: ["core", "math"],
+  },
+  handler: async (input: ModInput): Promise<number> => {
+    return input.a % input.b;
+  },
+});
+
+// =============================================================================
+// Abs Procedure
+// =============================================================================
+
+interface AbsInput {
+  value: number;
+}
+
+const AbsInputSchema = z.object({
+  value: z.number().describe("The value"),
+});
+
+type AbsProcedure = Procedure<AbsInput, number, { description: string; tags: string[] }>;
+
+const absProcedure: AbsProcedure = defineProcedure({
+  path: ["abs"],
+  input: AbsInputSchema,
+  output: numberOutput("The absolute value"),
+  metadata: {
+    description: "Absolute value",
+    tags: ["core", "math"],
+  },
+  handler: async (input: AbsInput): Promise<number> => {
+    return Math.abs(input.value);
+  },
+});
+
+// =============================================================================
+// Min Procedure
+// =============================================================================
+
+interface MinInput {
+  values: number[];
+}
+
+const MinInputSchema = z.object({
+  values: z.array(z.number()).describe("The values"),
+});
+
+type MinProcedure = Procedure<MinInput, number, { description: string; tags: string[] }>;
+
+const minProcedure: MinProcedure = defineProcedure({
+  path: ["min"],
+  input: MinInputSchema,
+  output: numberOutput("The smallest value"),
+  metadata: {
+    description: "Minimum value from array",
+    tags: ["core", "math"],
+  },
+  handler: async (input: MinInput): Promise<number> => {
+    if (input.values.length === 0) {
+      return Infinity;
+    }
+    return Math.min(...input.values);
+  },
+});
+
+// =============================================================================
+// Max Procedure
+// =============================================================================
+
+interface MaxInput {
+  values: number[];
+}
+
+const MaxInputSchema = z.object({
+  values: z.array(z.number()).describe("The values"),
+});
+
+type MaxProcedure = Procedure<MaxInput, number, { description: string; tags: string[] }>;
+
+const maxProcedure: MaxProcedure = defineProcedure({
+  path: ["max"],
+  input: MaxInputSchema,
+  output: numberOutput("The largest value"),
+  metadata: {
+    description: "Maximum value from array",
+    tags: ["core", "math"],
+  },
+  handler: async (input: MaxInput): Promise<number> => {
+    if (input.values.length === 0) {
+      return -Infinity;
+    }
+    return Math.max(...input.values);
+  },
+});
+
+// =============================================================================
+// Sum Procedure
+// =============================================================================
+
+interface SumInput {
+  values: number[];
+}
+
+const SumInputSchema = z.object({
+  values: z.array(z.number()).describe("The values"),
+});
+
+type SumProcedure = Procedure<SumInput, number, { description: string; tags: string[] }>;
+
+const sumProcedure: SumProcedure = defineProcedure({
+  path: ["sum"],
+  input: SumInputSchema,
+  output: numberOutput("The sum of the values"),
+  metadata: {
+    description: "Sum of all values in array",
+    tags: ["core", "math"],
+  },
+  handler: async (input: SumInput): Promise<number> => {
+    return input.values.reduce((acc, val) => acc + val, 0);
+  },
+});
+
+// =============================================================================
+// Pow Procedure
+// =============================================================================
+
+interface PowInput {
+  base: number;
+  exp: number;
+}
+
+const PowInputSchema = z.object({
+  base: z.number().describe("The base"),
+  exp: z.number().describe("The exponent"),
+});
+
+type PowProcedure = Procedure<PowInput, number, { description: string; tags: string[] }>;
+
+const powProcedure: PowProcedure = defineProcedure({
+  path: ["pow"],
+  input: PowInputSchema,
+  output: numberOutput("The base to the power of the exponent"),
+  metadata: {
+    description: "Raise base to exponent power",
+    tags: ["core", "math"],
+  },
+  handler: async (input: PowInput): Promise<number> => {
+    return Math.pow(input.base, input.exp);
+  },
+});
+
+// =============================================================================
+// Sqrt Procedure
+// =============================================================================
+
+interface SqrtInput {
+  value: number;
+}
+
+const SqrtInputSchema = z.object({
+  value: z.number().describe("The value"),
+});
+
+type SqrtProcedure = Procedure<SqrtInput, number, { description: string; tags: string[] }>;
+
+const sqrtProcedure: SqrtProcedure = defineProcedure({
+  path: ["sqrt"],
+  input: SqrtInputSchema,
+  output: numberOutput("The square root"),
+  metadata: {
+    description: "Square root",
+    tags: ["core", "math"],
+  },
+  handler: async (input: SqrtInput): Promise<number> => {
+    return Math.sqrt(input.value);
+  },
+});
+
+// =============================================================================
+// Floor Procedure
+// =============================================================================
+
+interface FloorInput {
+  value: number;
+}
+
+const FloorInputSchema = z.object({
+  value: z.number().describe("The value"),
+});
+
+type FloorProcedure = Procedure<FloorInput, number, { description: string; tags: string[] }>;
+
+const floorProcedure: FloorProcedure = defineProcedure({
+  path: ["floor"],
+  input: FloorInputSchema,
+  output: numberOutput("The value rounded down"),
+  metadata: {
+    description: "Round down to nearest integer",
+    tags: ["core", "math"],
+  },
+  handler: async (input: FloorInput): Promise<number> => {
+    return Math.floor(input.value);
+  },
+});
+
+// =============================================================================
+// Ceil Procedure
+// =============================================================================
+
+interface CeilInput {
+  value: number;
+}
+
+const CeilInputSchema = z.object({
+  value: z.number().describe("The value"),
+});
+
+type CeilProcedure = Procedure<CeilInput, number, { description: string; tags: string[] }>;
+
+const ceilProcedure: CeilProcedure = defineProcedure({
+  path: ["ceil"],
+  input: CeilInputSchema,
+  output: numberOutput("The value rounded up"),
+  metadata: {
+    description: "Round up to nearest integer",
+    tags: ["core", "math"],
+  },
+  handler: async (input: CeilInput): Promise<number> => {
+    return Math.ceil(input.value);
+  },
+});
+
+// =============================================================================
+// Round Procedure
+// =============================================================================
+
+interface RoundInput {
+  value: number;
+  decimals?: number | undefined;
+}
+
+const RoundInputSchema = z.object({
+  value: z.number().describe("The value"),
+  decimals: z.number().optional().describe("The number of decimal places (default: 0)"),
+});
+
+type RoundProcedure = Procedure<RoundInput, number, { description: string; tags: string[] }>;
+
+const roundProcedure: RoundProcedure = defineProcedure({
+  path: ["round"],
+  input: RoundInputSchema,
+  output: numberOutput("The value rounded to the nearest number"),
+  metadata: {
+    description: "Round to nearest integer or specified decimal places",
+    tags: ["core", "math"],
+  },
+  handler: async (input: RoundInput): Promise<number> => {
+    const decimals = input.decimals ?? 0;
+    const factor = Math.pow(10, decimals);
+    return Math.round(input.value * factor) / factor;
+  },
+});
+
+// =============================================================================
+// Export Math Procedures
+// =============================================================================
+
+/**
+ * All math procedures (before namespacing).
+ */
+const mathProceduresRaw: AnyProcedure[] = [
+  addProcedure as AnyProcedure,
+  subtractProcedure as AnyProcedure,
+  multiplyProcedure as AnyProcedure,
+  divideProcedure as AnyProcedure,
+  modProcedure as AnyProcedure,
+  absProcedure as AnyProcedure,
+  minProcedure as AnyProcedure,
+  maxProcedure as AnyProcedure,
+  sumProcedure as AnyProcedure,
+  powProcedure as AnyProcedure,
+  sqrtProcedure as AnyProcedure,
+  floorProcedure as AnyProcedure,
+  ceilProcedure as AnyProcedure,
+  roundProcedure as AnyProcedure,
+];
+
+/**
+ * All math procedures namespaced under "client".
+ */
+export const mathProcedures: AnyProcedure[] = namespace(["client"], mathProceduresRaw);
+
+/**
+ * Math procedures module for registration.
+ */
+export const mathModule: { name: string; procedures: AnyProcedure[] } = {
+  name: "client-math",
+  procedures: mathProcedures,
+};
+
+// Re-export individual procedures for direct access
+export {
+  addProcedure,
+  subtractProcedure,
+  multiplyProcedure,
+  divideProcedure,
+  modProcedure,
+  absProcedure,
+  minProcedure,
+  maxProcedure,
+  sumProcedure,
+  powProcedure,
+  sqrtProcedure,
+  floorProcedure,
+  ceilProcedure,
+  roundProcedure,
+};