@marasuchus/domain

Domain types and helpers, published as a public package on npmjs.com. ESM only, types included.

Installation

pnpm add @marasuchus/domain

zod is an optional peer: install it only if you use ./validation (see table below).

Modules

Each module is imported via subpath, with no barrel loading everything:

import { Result } from "@marasuchus/domain/result";

| Subpath | Status | Required peers | | -------------- | ----------- | -------------- | | ./result | implemented | none | | ./pagination | implemented | none | | ./validation | implemented | zod |

result

Result<T, E> models success or failure without throwing exceptions. DomainError is the union of ValidationError and NotFoundError.

import { Result } from "@marasuchus/domain/result";

const found = Result.ok(user);
const missing = Result.notFound("User not found", "User", id);
const invalid = Result.validation("Invalid input", { email: "Invalid email" });

if (!found.ok) {
  // found.error: DomainError
}

Result.err builds an arbitrary error when the E type is not DomainError.

pagination

Base types for paginated listings, plus the constant SortDirection derives from.

import {
  SORT_DIRECTION,
  type BaseQuery,
  type PaginatedResult,
  type SortDirection,
} from "@marasuchus/domain/pagination";

const page: PaginatedResult<{ id: number }> = {
  data: [{ id: 1 }],
  count: 42,
  page: 2,
  pageSize: 15,
  pageCount: 3,
};

validation

zod schemas and helpers for query params and forms: they all tolerate null, undefined, and empty strings (returning undefined or a default instead of failing).

• sortDirSchema / sortDirDescSchema: "asc" | "desc", defaulting to "asc" / "desc" on invalid input.
• optionalPositiveInt, optionalInt, optionalNumber: coerce strings to numbers; undefined when there is no value or it is invalid.
• optionalTrue: only true, "true", or "1" return true; everything else is undefined (useful for checkboxes).
• optionalDateOnly: accepts YYYY-MM-DD only.
• optionalTextFilter: trim + 255 character max.
• parseFormBoolean(value, fallback): parses "true"/"1" and "false"/"0", falling back to fallback for anything else.
• createPaginatedQuerySchema(sortOptions, defaultSortBy, defaultSortDir, { defaultPageSize, maxPageSize }): valida page (default 1), pageSize (clamped a maxPageSize, default a defaultPageSize), sortBy y sortDir con sus defaults.

import {
  createPaginatedQuerySchema,
  optionalPositiveInt,
  sortDirSchema,
} from "@marasuchus/domain/validation";

const querySchema = createPaginatedQuerySchema(
  ["name", "createdAt"] as const,
  "name",
  "asc",
  {
    defaultPageSize: 15,
    maxPageSize: 100,
  },
);

License

MIT — see LICENSE.