@beignet/core 0.0.1

package/src/domain/value-object.ts

@@ -0,0 +1,135 @@
+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
+ */
+async function validateSchema<T>(
+  schema: StandardSchemaV1<unknown, T>,
+  data: unknown,
+): Promise<T> {
+  const result = await schema["~standard"].validate(data);
+  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");
+}
+
+/**
+ * Check if data is valid according to a Standard Schema
+ */
+async function isValid<T>(
+  schema: StandardSchemaV1<unknown, T>,
+  data: unknown,
+): Promise<boolean> {
+  const result = await schema["~standard"].validate(data);
+  return !result.issues?.length && "value" in result;
+}
+
+/**
+ * Represents a defined Value Object with validation and type information.
+ */
+export interface ValueObjectDef<
+  Name extends string,
+  Schema extends StandardSchema,
+> {
+  /** The name of this value object (for debugging/introspection) */
+  name: Name;
+  /** The schema used for validation (any Standard Schema compatible) */
+  schema: Schema;
+  /** Create a validated value object from unknown input (async due to Standard Schema) */
+  create(input: unknown): Promise<InferOutput<Schema>>;
+  /** Type guard to check if an input is valid for this value object (async due to Standard Schema) */
+  isValid(input: unknown): Promise<boolean>;
+  /** Type alias for the inferred TypeScript type */
+  Type: InferOutput<Schema>;
+}
+
+/**
+ * Builder class for creating Value Objects.
+ */
+class ValueObjectBuilder<Name extends string, Schema extends StandardSchema> {
+  constructor(
+    private readonly cfg: {
+      name: Name;
+      schema?: Schema;
+    },
+  ) {}
+
+  /**
+   * Set the schema for this value object.
+   */
+  schema<S extends StandardSchema>(s: S): ValueObjectBuilder<Name, S> {
+    return new ValueObjectBuilder<Name, S>({ ...this.cfg, schema: s });
+  }
+
+  /**
+   * Finalize the value object definition.
+   */
+  build(): ValueObjectDef<Name, Schema> {
+    if (!this.cfg.schema) {
+      throw new Error(`Value object "${this.cfg.name}" is missing a schema`);
+    }
+
+    const schemaToUse = this.cfg.schema;
+
+    const def: ValueObjectDef<Name, Schema> = {
+      name: this.cfg.name,
+      schema: schemaToUse,
+      async create(input: unknown) {
+        return validateSchema(schemaToUse, input);
+      },
+      async isValid(input: unknown) {
+        return isValid(schemaToUse, input);
+      },
+      // Type is undefined at runtime - used only for TypeScript type inference via `typeof ValueObject.Type`
+      Type: undefined as unknown as InferOutput<Schema>,
+    };
+
+    return def;
+  }
+}
+
+/**
+ * Create a new Value Object builder.
+ *
+ * @example
+ * ```ts
+ * const Email = defineValueObject("Email")
+ *   .schema(z.string().email())
+ *   .build();
+ *
+ * type Email = typeof Email.Type;
+ *
+ * const email = await Email.create("test@example.com"); // OK
+ * const isValid = await Email.isValid("test@example.com"); // true
+ * ```
+ */
+export function defineValueObject<Name extends string>(name: Name) {
+  // biome-ignore lint/suspicious/noExplicitAny: Initial schema type is never, will be set via .schema()
+  return new ValueObjectBuilder<Name, never>({ name } as any);
+}

package/src/errors/catalog.ts

@@ -0,0 +1,149 @@
+/**
+ * Error catalog and AppError definitions for Beignet
+ */
+
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+type ErrorDetailsSchema = StandardSchemaV1<unknown, unknown>;
+const APP_ERROR_BRAND = Symbol.for("beignet.AppError");
+
+/**
+ * Definition of a single error in the catalog
+ */
+export interface ErrorDef<
+  TDetails extends ErrorDetailsSchema | undefined =
+    | ErrorDetailsSchema
+    | undefined,
+> {
+  /** Unique, stable code used across layers (e.g. "TODO_NOT_FOUND") */
+  code: string;
+  /** HTTP status code (e.g. 404, 401, 409, 422, 500, etc.) */
+  status: number;
+  /** Default human-readable message */
+  message: string;
+  /** Optional schema for the structured details value */
+  details?: TDetails;
+}
+
+/**
+ * A mapping of keys to error definitions.
+ * Keys can be friendly identifiers, e.g. "TodoNotFound".
+ */
+export type ErrorCatalog = Record<string, ErrorDef>;
+
+export type InferErrorDetails<TDef extends ErrorDef> = TDef extends {
+  details: ErrorDetailsSchema;
+}
+  ? StandardSchemaV1.InferInput<TDef["details"]>
+  : unknown;
+
+/**
+ * Type-preserving helper to define an error catalog.
+ */
+export function defineErrors<const T extends ErrorCatalog>(defs: T): T {
+  return defs;
+}
+
+/**
+ * Application error class that domain & application code can throw.
+ * Contains the error definition from the catalog and optional structured details.
+ */
+export class AppError<TDef extends ErrorDef = ErrorDef> extends Error {
+  readonly [APP_ERROR_BRAND] = true;
+  /** The error definition from the catalog */
+  readonly def: TDef;
+  /** Optional structured details (for debugging, UI, etc.) */
+  readonly details?: InferErrorDetails<TDef>;
+
+  constructor(
+    def: TDef,
+    details?: InferErrorDetails<TDef>,
+    overrideMessage?: string,
+    options?: { cause?: unknown },
+  ) {
+    super(overrideMessage ?? def.message, { cause: options?.cause });
+    this.name = "AppError";
+    this.def = def;
+    this.details = details;
+  }
+
+  get code(): string {
+    return this.def.code;
+  }
+
+  get status(): number {
+    return this.def.status;
+  }
+}
+
+/**
+ * Callable helper for creating AppErrors from a catalog.
+ */
+export type AppErrorCreator<TCatalog extends ErrorCatalog> = {
+  catalog: TCatalog;
+  /**
+   * Create an AppError from a catalog key.
+   */
+  <Key extends keyof TCatalog>(
+    key: Key,
+    options?: {
+      cause?: unknown;
+      details?: InferErrorDetails<TCatalog[Key]>;
+      message?: string;
+    },
+  ): AppError<TCatalog[Key]>;
+};
+
+/**
+ * Create a callable AppError helper bound to a specific catalog.
+ */
+export function createAppError<const T extends ErrorCatalog>(
+  catalog: T,
+): AppErrorCreator<T> {
+  const appError = (<Key extends keyof T>(
+    key: Key,
+    options?: {
+      cause?: unknown;
+      details?: InferErrorDetails<T[Key]>;
+      message?: string;
+    },
+  ): AppError<T[Key]> => {
+    const def = catalog[key as keyof T] as T[typeof key] | undefined;
+    if (!def) {
+      throw new Error(`Unknown error catalog key: ${String(key)}`);
+    }
+    return new AppError<T[typeof key]>(
+      def,
+      options?.details,
+      options?.message,
+      {
+        cause: options?.cause,
+      },
+    );
+  }) as AppErrorCreator<T>;
+
+  appError.catalog = catalog;
+  return appError;
+}
+
+/**
+ * Type guard to check if an unknown error is an AppError
+ */
+export function isAppError(err: unknown): err is AppError<ErrorDef> {
+  if (err instanceof AppError) return true;
+  if (typeof err !== "object" || err === null) return false;
+
+  const value = err as Record<PropertyKey, unknown>;
+  if (value[APP_ERROR_BRAND] === true) return true;
+  if (value.name !== "AppError") return false;
+
+  const def = value.def;
+  if (typeof def !== "object" || def === null) return false;
+
+  const errorDef = def as Record<string, unknown>;
+  return (
+    typeof errorDef.code === "string" &&
+    typeof errorDef.status === "number" &&
+    typeof errorDef.message === "string"
+  );
+}

package/src/errors/http.ts

@@ -0,0 +1,80 @@
+/**
+ * Standard HTTP error catalog
+ *
+ * A base catalog of common HTTP-related errors that apps can reuse and extend.
+ */
+
+import { defineErrors } from "./catalog";
+
+/**
+ * A base catalog of common HTTP-related errors.
+ *
+ * Apps can spread this into their own error catalog:
+ *
+ * @example
+ * ```ts
+ * import { defineErrors } from "@beignet/core/errors";
+ * import { httpErrors } from "@beignet/core/errors/http";
+ *
+ * export const errors = defineErrors({
+ *   ...httpErrors,
+ *   TodoNotFound: {
+ *     code: "TODO_NOT_FOUND",
+ *     status: 404,
+ *     message: "Todo not found",
+ *   },
+ * });
+ * ```
+ */
+export const httpErrors = defineErrors({
+  BadRequest: {
+    code: "BAD_REQUEST",
+    status: 400,
+    message: "Bad request",
+  },
+  Unauthorized: {
+    code: "UNAUTHORIZED",
+    status: 401,
+    message: "Unauthorized",
+  },
+  Forbidden: {
+    code: "FORBIDDEN",
+    status: 403,
+    message: "Forbidden",
+  },
+  NotFound: {
+    code: "NOT_FOUND",
+    status: 404,
+    message: "Resource not found",
+  },
+  Conflict: {
+    code: "CONFLICT",
+    status: 409,
+    message: "Conflict",
+  },
+  TooManyRequests: {
+    code: "TOO_MANY_REQUESTS",
+    status: 429,
+    message: "Too many requests",
+  },
+  UnprocessableEntity: {
+    code: "UNPROCESSABLE_ENTITY",
+    status: 422,
+    message: "Unprocessable entity",
+  },
+  ValidationError: {
+    code: "VALIDATION_ERROR",
+    status: 422,
+    message: "Validation failed",
+  },
+  InternalServerError: {
+    code: "INTERNAL_SERVER_ERROR",
+    status: 500,
+    message: "Internal server error",
+  },
+});
+
+/**
+ * Type of the default HTTP error catalog.
+ */
+export type HttpErrorCatalog = typeof httpErrors;

package/src/errors/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @beignet/core/errors
+ *
+ * Error catalog and error handling utilities for Beignet
+ */
+
+// Error catalog and AppError
+export {
+  AppError,
+  type AppErrorCreator,
+  createAppError,
+  defineErrors,
+  type ErrorCatalog,
+  type ErrorDef,
+  type InferErrorDetails,
+  isAppError,
+} from "./catalog";
+// HTTP error helpers
+export { type HttpErrorCatalog, httpErrors } from "./http";
+// Error response utilities
+export {
+  createErrorResponseBody,
+  type ErrorResponseBody,
+  isErrorResponseBody,
+  toErrorResponseBody,
+} from "./response";
+// Schema validation error (shared across client/core/server)
+export { SchemaValidationError, type ValidationIssue } from "./validation";

package/src/errors/response.ts

@@ -0,0 +1,54 @@
+/**
+ * Standard error response schema and utilities for Beignet
+ */
+
+import type { AppError, ErrorDef } from "./catalog";
+
+/**
+ * Standard error response body structure
+ */
+export interface ErrorResponseBody {
+  code: string;
+  message: string;
+  details?: unknown;
+  requestId?: string;
+}
+
+/**
+ * Create a standard error response body.
+ */
+export function createErrorResponseBody(
+  args: ErrorResponseBody,
+): ErrorResponseBody {
+  return {
+    code: args.code,
+    message: args.message,
+    ...(args.details !== undefined ? { details: args.details } : {}),
+    ...(args.requestId !== undefined ? { requestId: args.requestId } : {}),
+  };
+}
+
+/**
+ * Check whether a value is a standard error response body.
+ */
+export function isErrorResponseBody(
+  value: unknown,
+): value is ErrorResponseBody {
+  if (typeof value !== "object" || value === null) return false;
+
+  const body = value as Record<string, unknown>;
+  return typeof body.code === "string" && typeof body.message === "string";
+}
+
+/**
+ * Convert an AppError to a standard error response body
+ */
+export function toErrorResponseBody(
+  err: AppError<ErrorDef>,
+): ErrorResponseBody {
+  return createErrorResponseBody({
+    code: err.code,
+    message: err.message,
+    details: err.details,
+  });
+}

package/src/errors/validation.ts

@@ -0,0 +1,35 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/**
+ * Normalized validation issue with simplified path
+ */
+export interface ValidationIssue {
+  path?: (string | number)[];
+  message: string;
+}
+
+/**
+ * Error thrown when Standard Schema validation fails.
+ * Shared across client and server packages so `instanceof` checks work
+ * regardless of which package threw the error.
+ */
+export class SchemaValidationError extends Error {
+  readonly issues: ReadonlyArray<ValidationIssue>;
+
+  constructor(rawIssues: ReadonlyArray<StandardSchemaV1.Issue>) {
+    const issues: ValidationIssue[] = rawIssues.map((i) => ({
+      path: i.path?.map((p) => (typeof p === "object" ? p.key : p)) as
+        | (string | number)[]
+        | undefined,
+      message: i.message,
+    }));
+    const message = issues
+      .map((i) =>
+        i.path?.length ? `${i.path.join(".")}: ${i.message}` : i.message,
+      )
+      .join("; ");
+    super(message);
+    this.name = "SchemaValidationError";
+    this.issues = issues;
+  }
+}