@beignet/core 0.0.1

package/src/contracts/rate-limit.ts

@@ -0,0 +1,50 @@
+/**
+ * Rate limit scope for identifying the rate limit key.
+ *
+ * - "user": keyed by authenticated user id
+ * - "ip": keyed by client IP
+ * - "global": single global key
+ */
+export type RateLimitScope = "user" | "ip" | "global";
+
+/**
+ * Rate limit configuration for a contract.
+ *
+ * This type is used in contract metadata to configure rate limiting behavior.
+ *
+ * @example
+ * ```ts
+ * const getTodoContract = c
+ *   .get("/api/todos/:id", "getTodo")
+ *   .pathParams(z.object({ id: z.string() }))
+ *   .meta({
+ *     auth: "required",
+ *     rateLimit: {
+ *       max: 60,
+ *       windowSec: 60,
+ *       scope: "user",
+ *     },
+ *   })
+ *   .responses({ 200: z.object({ id: z.string(), name: z.string() }) });
+ * ```
+ */
+export interface RateLimitMeta {
+  /**
+   * Maximum number of allowed hits within the window.
+   */
+  max: number;
+  /**
+   * Length of the window in seconds.
+   */
+  windowSec: number;
+  /**
+   * Scope for identifying the rate limit key.
+   *
+   * - "user": keyed by authenticated user id
+   * - "ip": keyed by client IP
+   * - "global": single global key
+   *
+   * Default: "global".
+   */
+  scope?: RateLimitScope;
+}

package/src/contracts/types.ts

@@ -0,0 +1,207 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { OpenAPIOperationMeta } from "./openapi-meta";
+import type { RateLimitMeta } from "./rate-limit";
+
+/**
+ * Any Standard Schema validator type
+ * Replaces ZodTypeAny to support all Standard Schema compatible libraries
+ */
+export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+
+export type ContractResponseSchema = StandardSchema | null;
+export type ContractResponses = Partial<Record<number, ContractResponseSchema>>;
+export type StandardErrorResponseBody = {
+  code: string;
+  message: string;
+  details?: unknown;
+  requestId?: string;
+};
+export type StandardErrorResponseSchema = StandardSchemaV1<
+  unknown,
+  StandardErrorResponseBody
+>;
+export type ContractErrorDefinition = {
+  code: string;
+  status: number;
+  message: string;
+  details?: StandardSchema;
+};
+export type ContractErrorResponses = Record<string, ContractErrorDefinition>;
+export type ResponsesFromErrorDefinitions<T extends ContractErrorResponses> = {
+  [K in keyof T as T[K]["status"]]: StandardErrorResponseSchema;
+};
+export type ContractHeaderSchemas =
+  | StandardSchema
+  | readonly StandardSchema[]
+  | null;
+
+export const BEIGNET_ERROR_OWNER_HEADER = "x-beignet-error-owner";
+
+export type InferHeaderSchemaInput<
+  T extends ContractHeaderSchemas | undefined,
+> = T extends readonly StandardSchemaV1[]
+  ? UnionToIntersection<InferInput<T[number]>>
+  : T extends StandardSchemaV1
+    ? InferInput<T>
+    : undefined;
+
+export type InferHeaderSchemaOutput<
+  T extends ContractHeaderSchemas | undefined,
+> = T extends readonly StandardSchemaV1[]
+  ? UnionToIntersection<InferOutput<T[number]>>
+  : T extends StandardSchemaV1
+    ? InferOutput<T>
+    : undefined;
+
+type UnionToIntersection<T> = (
+  T extends unknown
+    ? (value: T) => void
+    : never
+) extends (value: infer I) => void
+  ? I
+  : never;
+
+/**
+ * Infer the output type from a Standard Schema
+ */
+export type InferOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+/**
+ * Infer the input type from a Standard Schema
+ */
+export type InferInput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferInput<T>;
+
+/**
+ * HTTP methods supported by contracts
+ */
+export type HttpMethod =
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE"
+  | "HEAD"
+  | "OPTIONS";
+
+export type BodyHttpMethod = Extract<HttpMethod, "POST" | "PUT" | "PATCH">;
+
+export const BODY_HTTP_METHODS = [
+  "POST",
+  "PUT",
+  "PATCH",
+] as const satisfies readonly BodyHttpMethod[];
+
+export function methodSupportsRequestBody(
+  method: HttpMethod,
+): method is BodyHttpMethod {
+  return (BODY_HTTP_METHODS as readonly HttpMethod[]).includes(method);
+}
+
+export const STANDARD_ERROR_RESPONSE_SCHEMA: StandardErrorResponseSchema = {
+  "~standard": {
+    version: 1,
+    vendor: "beignet",
+    validate(value) {
+      if (typeof value !== "object" || value === null) {
+        return {
+          issues: [{ message: "Expected error response body object." }],
+        };
+      }
+
+      const body = value as Record<string, unknown>;
+      const issues: StandardSchemaV1.Issue[] = [];
+      if (typeof body.code !== "string") {
+        issues.push({ message: 'Expected "code" to be a string.' });
+      }
+      if (typeof body.message !== "string") {
+        issues.push({ message: 'Expected "message" to be a string.' });
+      }
+      if (body.requestId !== undefined && typeof body.requestId !== "string") {
+        issues.push({ message: 'Expected "requestId" to be a string.' });
+      }
+      if (issues.length) {
+        return { issues };
+      }
+
+      return {
+        value: {
+          code: body.code as string,
+          message: body.message as string,
+          ...(body.details !== undefined ? { details: body.details } : {}),
+          ...(body.requestId !== undefined
+            ? { requestId: body.requestId as string }
+            : {}),
+        },
+      };
+    },
+  },
+};
+
+/**
+ * Contract metadata - freeform object for policies, auth, etc.
+ * May include an optional openapi namespace for OpenAPI-specific metadata,
+ * and an optional rateLimit namespace for rate limiting configuration.
+ */
+export type ContractMeta = {
+  openapi?: OpenAPIOperationMeta;
+  /**
+   * Optional rate limit configuration for this contract.
+   *
+   * If absent, no rate limiting is applied.
+   */
+  rateLimit?: RateLimitMeta;
+  [namespace: string]: unknown;
+};
+
+/**
+ * HTTP contract configuration
+ */
+export type HttpContractConfig<
+  TMethod extends HttpMethod = HttpMethod,
+  TPathParams extends StandardSchema | null = StandardSchema | null,
+  TQuery extends StandardSchema | null = StandardSchema | null,
+  TBody extends StandardSchema | null = StandardSchema | null,
+  TResponses extends ContractResponses = ContractResponses,
+  TMeta extends ContractMeta = ContractMeta,
+  TPath extends string = string,
+  THeaders extends ContractHeaderSchemas = ContractHeaderSchemas,
+> = {
+  kind: "http";
+  /**
+   * Fully qualified contract name. Contracts created from a namespaced
+   * ContractGroup use `${namespace}.${localName}`.
+   */
+  name: string;
+  /**
+   * Optional resource namespace for contracts created from a ContractGroup.
+   */
+  namespace?: string;
+  /**
+   * Contract name without the resource namespace.
+   */
+  localName?: string;
+  method: TMethod;
+  path: TPath;
+  pathParams: TPathParams;
+  query: TQuery;
+  headers?: THeaders;
+  body: TBody;
+  responses: TResponses;
+  metadata: TMeta;
+};
+
+/**
+ * Any contract type
+ */
+export type AnyContract = HttpContractConfig;
+
+export function getContractHeaderSchemas(
+  headers: ContractHeaderSchemas | undefined,
+): readonly StandardSchema[] {
+  if (!headers) return [];
+  return Array.isArray(headers)
+    ? (headers as readonly StandardSchema[])
+    : [headers as StandardSchema];
+}

package/src/contracts/utils.ts

@@ -0,0 +1,56 @@
+import { type PathTemplateSegment, parsePathTemplate } from "./path-template";
+import type { HttpMethod } from "./types";
+
+const methodNameMap: Record<HttpMethod, string> = {
+  GET: "get",
+  POST: "create",
+  PUT: "update",
+  PATCH: "patch",
+  DELETE: "delete",
+  HEAD: "head",
+  OPTIONS: "options",
+};
+
+function toPascalCase(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+function getMeaningfulPathSegments(path: string): PathTemplateSegment[] {
+  const segments = parsePathTemplate(path).segments;
+
+  if (
+    segments[0]?.kind === "static" &&
+    segments[0].value.toLowerCase() === "api"
+  ) {
+    return segments.slice(1);
+  }
+
+  return segments;
+}
+
+export function generateContractName(method: HttpMethod, path: string): string {
+  const methodPrefix = methodNameMap[method];
+  const segments = getMeaningfulPathSegments(path);
+
+  if (segments.length === 0) {
+    return `${methodPrefix}Root`;
+  }
+
+  const nameSuffix = segments
+    .map((segment) => {
+      if (segment.kind === "dynamic") {
+        const paramName = toPascalCase(segment.name);
+        return `By${paramName || "Param"}`;
+      }
+
+      return toPascalCase(segment.value) || "Resource";
+    })
+    .join("");
+
+  return `${methodPrefix}${nameSuffix}`;
+}

package/src/domain/entity.ts

@@ -0,0 +1,256 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/**
+ * Any Standard Schema validator type
+ */
+export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+
+/**
+ * Infer the output type from a Standard Schema
+ */
+export type InferOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+/**
+ * Validate data using a Standard Schema validator synchronously if possible
+ */
+function validateSchemaSync<T>(
+  schema: StandardSchemaV1<unknown, T>,
+  data: unknown,
+): T | Promise<T> {
+  const result = schema["~standard"].validate(data);
+
+  if (result instanceof Promise) {
+    return result.then((resolved) => {
+      if (resolved.issues?.length) {
+        const message = resolved.issues
+          .map((issue) => {
+            const path =
+              issue.path !== undefined
+                ? Array.isArray(issue.path)
+                  ? issue.path.join(".")
+                  : String(issue.path)
+                : "";
+            return path ? `${path}: ${issue.message}` : issue.message;
+          })
+          .join("; ");
+        throw new Error(`Validation failed: ${message}`);
+      }
+      if ("value" in resolved) {
+        return resolved.value;
+      }
+      throw new Error("Invalid Standard Schema result: missing value");
+    });
+  }
+
+  if (result.issues?.length) {
+    const message = result.issues
+      .map((issue) => {
+        const path =
+          issue.path !== undefined
+            ? Array.isArray(issue.path)
+              ? issue.path.join(".")
+              : String(issue.path)
+            : "";
+        return path ? `${path}: ${issue.message}` : issue.message;
+      })
+      .join("; ");
+    throw new Error(`Validation failed: ${message}`);
+  }
+  if ("value" in result) {
+    return result.value;
+  }
+  throw new Error("Invalid Standard Schema result: missing value");
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: Base methods type for flexibility
+type AnyMethods = Record<string, any>;
+
+/**
+ * Represents an instance of an entity with props, methods, and immutable update capability.
+ */
+export type EntityInstance<
+  Name extends string,
+  Schema extends StandardSchema,
+  Methods extends AnyMethods,
+> = InferOutput<Schema> & {
+  /**
+   * Create a new entity instance with updated properties (immutable update).
+   */
+  with(
+    patch: Partial<InferOutput<Schema>>,
+  ):
+    | EntityInstance<Name, Schema, Methods>
+    | Promise<EntityInstance<Name, Schema, Methods>>;
+  /**
+   * Convert the entity to a plain JSON object for persistence.
+   */
+  toJSON(): InferOutput<Schema>;
+} & Methods;
+
+/**
+ * Represents a defined Entity with schema and factory methods.
+ */
+export interface EntityDef<
+  Name extends string,
+  Schema extends StandardSchema,
+  Methods extends AnyMethods,
+> {
+  /** The name of this entity (for debugging/introspection) */
+  name: Name;
+  /** The Standard Schema for validating entity props */
+  schema: Schema;
+  /** Create a new entity instance from props */
+  create(
+    props: InferOutput<Schema>,
+  ):
+    | EntityInstance<Name, Schema, Methods>
+    | Promise<EntityInstance<Name, Schema, Methods>>;
+  /** Reconstruct an entity instance from JSON (e.g., from persistence) */
+  fromJSON(
+    json: InferOutput<Schema>,
+  ):
+    | EntityInstance<Name, Schema, Methods>
+    | Promise<EntityInstance<Name, Schema, Methods>>;
+  /** Type alias for the entity instance type */
+  Type: EntityInstance<Name, Schema, Methods>;
+}
+
+/**
+ * Builder class for creating Entities/Aggregates.
+ */
+class EntityBuilder<
+  Name extends string,
+  Schema extends StandardSchema,
+  Methods extends AnyMethods,
+> {
+  constructor(
+    private readonly cfg: {
+      name: Name;
+      schema?: Schema;
+      // biome-ignore lint/suspicious/noExplicitAny: Methods builder receives base instance
+      methods?: (self: any) => Methods;
+    },
+  ) {}
+
+  /**
+   * Define the schema for this entity using any Standard Schema compatible validator.
+   */
+  props<S extends StandardSchema>(schema: S): EntityBuilder<Name, S, Methods> {
+    return new EntityBuilder<Name, S, Methods>({
+      name: this.cfg.name,
+      schema,
+      methods: this.cfg.methods,
+    });
+  }
+
+  /**
+   * Define methods to attach to entity instances.
+   * The method builder receives the base instance (with props, with, and toJSON).
+   */
+  methods<M extends AnyMethods>(
+    // biome-ignore lint/suspicious/noExplicitAny: Methods builder receives base instance with props
+    build: (self: any) => M,
+  ): EntityBuilder<Name, Schema, M> {
+    return new EntityBuilder<Name, Schema, M>({
+      name: this.cfg.name,
+      schema: this.cfg.schema,
+      methods: build,
+    });
+  }
+
+  /**
+   * Finalize and build the entity definition.
+   */
+  build(): EntityDef<Name, Schema, Methods> {
+    if (!this.cfg.schema) {
+      throw new Error(`Entity "${this.cfg.name}" is missing props schema`);
+    }
+
+    const schema = this.cfg.schema;
+    const methodsBuilder = this.cfg.methods;
+
+    const createInstance = (
+      raw: InferOutput<Schema>,
+    ):
+      | EntityInstance<Name, Schema, Methods>
+      | Promise<EntityInstance<Name, Schema, Methods>> => {
+      const validationResult = validateSchemaSync(schema, raw);
+
+      const buildInstance = (
+        parsed: InferOutput<Schema>,
+      ): EntityInstance<Name, Schema, Methods> => {
+        // Cast parsed to a plain object for spreading
+        const parsedObj = parsed as Record<string, unknown>;
+
+        // biome-ignore lint/suspicious/noExplicitAny: Dynamic object construction
+        const base: any = {
+          ...parsedObj,
+          // Immutable update - creates a new validated instance
+          // Note: Re-validates the merged props for data integrity
+          with(patch: Partial<InferOutput<Schema>>) {
+            const patchObj = patch as Record<string, unknown>;
+            return createInstance({
+              ...parsedObj,
+              ...patchObj,
+            } as InferOutput<Schema>);
+          },
+          toJSON() {
+            return parsed;
+          },
+        };
+
+        const methods = methodsBuilder?.(base) ?? {};
+        const instance = Object.freeze({
+          ...base,
+          ...methods,
+        }) as EntityInstance<Name, Schema, Methods>;
+
+        return instance;
+      };
+
+      if (validationResult instanceof Promise) {
+        return validationResult.then(buildInstance);
+      }
+      return buildInstance(validationResult);
+    };
+
+    const def: EntityDef<Name, Schema, Methods> = {
+      name: this.cfg.name,
+      schema,
+      create: createInstance,
+      fromJSON: createInstance,
+      // Type is undefined at runtime - used only for TypeScript type inference via `typeof Entity.Type`
+      Type: undefined as unknown as EntityInstance<Name, Schema, Methods>,
+    };
+
+    return def;
+  }
+}
+
+/**
+ * Create a new Entity builder.
+ *
+ * @example
+ * ```ts
+ * const Todo = defineEntity("Todo")
+ *   .props(z.object({
+ *     id: z.string(),
+ *     title: z.string(),
+ *     assigneeIds: z.array(z.string()).default([]),
+ *   }))
+ *   .methods((self) => ({
+ *     addAssignee(id: string) {
+ *       if (self.assigneeIds.includes(id)) return self;
+ *       return self.with({ assigneeIds: [...self.assigneeIds, id] });
+ *     },
+ *   }))
+ *   .build();
+ *
+ * type Todo = typeof Todo.Type;
+ * ```
+ */
+export function defineEntity<Name extends string>(name: Name) {
+  // biome-ignore lint/suspicious/noExplicitAny: Initial schema type will be set via .props()
+  return new EntityBuilder<Name, any, Record<string, never>>({ name } as any);
+}

package/src/domain/events.ts

@@ -0,0 +1,52 @@
+import type { EventDef, InferEventPayload, StandardSchema } from "../events";
+import { defineEvent } from "../events";
+
+/**
+ * Represents a defined Domain Event with name and payload schema.
+ */
+export type DomainEventDef<
+  Name extends string = string,
+  Payload extends StandardSchema = StandardSchema,
+> = EventDef<Name, Payload>;
+
+/**
+ * Infer the payload type from a DomainEventDef.
+ *
+ * @example
+ * ```ts
+ * const UserRegistered = defineDomainEvent(
+ *   "user.registered",
+ *   z.object({
+ *     userId: z.string(),
+ *     email: z.string().email(),
+ *   })
+ * );
+ *
+ * type Payload = InferEventPayload<typeof UserRegistered>;
+ * // { userId: string; email: string }
+ * ```
+ */
+export type { InferEventPayload };
+
+/**
+ * Create a new Domain Event definition.
+ *
+ * @example
+ * ```ts
+ * const UserRegistered = defineDomainEvent(
+ *   "user.registered",
+ *   z.object({
+ *     userId: z.string(),
+ *     email: z.string().email(),
+ *   })
+ * );
+ *
+ * type UserRegistered = typeof UserRegistered;
+ * ```
+ */
+export function defineDomainEvent<
+  Name extends string,
+  Payload extends StandardSchema,
+>(name: Name, payload: Payload): DomainEventDef<Name, Payload> {
+  return defineEvent(name, { payload });
+}

package/src/domain/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @beignet/core/domain
+ *
+ * Domain modeling helpers for Beignet - value objects, entities, and domain events.
+ *
+ * This package provides small, framework-agnostic helpers for domain modeling:
+ * - A Value Object builder (defineValueObject)
+ * - An Entity/Aggregate builder (defineEntity)
+ * - A Domain Event helper (defineDomainEvent)
+ */
+
+export { defineEntity, type EntityDef, type EntityInstance } from "./entity";
+export {
+  type DomainEventDef,
+  defineDomainEvent,
+  type InferEventPayload,
+} from "./events";
+export { defineValueObject, type ValueObjectDef } from "./value-object";