bazis 0.96.1

package/library/jsonapi/decorators.ts

@@ -0,0 +1,161 @@
+import type { FilterOperator, ListQueryOptions, PageOptions } from "./types";
+
+// Polyfill: Bun runs TC39 decorators natively, but Symbol.metadata may be
+// missing at runtime. Symbol.for gives one shared symbol for all module copies.
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+/** Key under which the list-request schema is stored in the class metadata. */
+const LIST_SCHEMA = Symbol.for("bazis:listing:schema");
+
+/** Permissions of one field: whether it is sortable and which filter operators are allowed. */
+export interface FieldSchema {
+  sortable: boolean;
+  readonly filterOps: FilterOperator[];
+}
+
+/** The whole request-class schema (fields + paging limits + allowed includes). */
+export interface ListSchema {
+  readonly fields: Record<string, FieldSchema>;
+  page?: PageOptions;
+  include?: readonly string[];
+}
+
+interface SchemaMetadata {
+  [LIST_SCHEMA]?: ListSchema;
+}
+
+/** Parameters of the {@link ListOptions} decorator (class level). */
+export interface ListOptionsConfig {
+  /** Default page size. */
+  readonly defaultSize?: number;
+  /** Maximum allowed page size. */
+  readonly maxSize?: number;
+  /** Allowed include paths (`?include=`). */
+  readonly include?: readonly string[];
+}
+
+/**
+ * TC39 decorator metadata is inherited prototypically: a subclass's metadata
+ * has the parent's metadata as its prototype. On the first write to a concrete
+ * class we copy on write so the parent schema is not mutated.
+ */
+function ensureOwnSchema(metadata: SchemaMetadata): ListSchema {
+  if (!Object.prototype.hasOwnProperty.call(metadata, LIST_SCHEMA)) {
+    const inherited = metadata[LIST_SCHEMA];
+    metadata[LIST_SCHEMA] = inherited
+      ? { fields: cloneFields(inherited.fields), page: inherited.page, include: inherited.include }
+      : { fields: {} };
+  }
+  return metadata[LIST_SCHEMA]!;
+}
+
+function cloneFields(fields: Record<string, FieldSchema>): Record<string, FieldSchema> {
+  const out: Record<string, FieldSchema> = {};
+  for (const [name, schema] of Object.entries(fields)) {
+    out[name] = { sortable: schema.sortable, filterOps: [...schema.filterOps] };
+  }
+  return out;
+}
+
+function fieldOf(schema: ListSchema, name: string): FieldSchema {
+  return (schema.fields[name] ??= { sortable: false, filterOps: [] });
+}
+
+function assertInstanceField(context: ClassFieldDecoratorContext, decorator: string): void {
+  if (context.static) {
+    throw new Error(`${decorator}: static field "${String(context.name)}" is not supported.`);
+  }
+  if (context.private) {
+    throw new Error(`${decorator}: private field "${String(context.name)}" is not supported.`);
+  }
+}
+
+/**
+ * Allows sorting by the field (`?sort=field` / `?sort=-field`).
+ *
+ * ```ts
+ * class UserListQuery extends ListRequest<User> {
+ *   @Sortable() name!: string;
+ * }
+ * ```
+ */
+export function Sortable() {
+  return (_value: undefined, context: ClassFieldDecoratorContext): void => {
+    assertInstanceField(context, "@Sortable");
+    fieldOf(ensureOwnSchema(context.metadata as SchemaMetadata), String(context.name)).sortable = true;
+  };
+}
+
+/**
+ * Allows filtering by the field with the listed operators
+ * (`?filter[field][op]=value`).
+ *
+ * ```ts
+ * class UserListQuery extends ListRequest<User> {
+ *   @Filterable("eq", "contains") name!: string;
+ *   @Filterable("gte", "lte", "in") age!: number;
+ * }
+ * ```
+ */
+export function Filterable(...operators: FilterOperator[]) {
+  return (_value: undefined, context: ClassFieldDecoratorContext): void => {
+    assertInstanceField(context, "@Filterable");
+    const field = fieldOf(ensureOwnSchema(context.metadata as SchemaMetadata), String(context.name));
+    for (const operator of operators) {
+      if (!field.filterOps.includes(operator)) {
+        field.filterOps.push(operator);
+      }
+    }
+  };
+}
+
+/**
+ * Paging limits and allowed includes for a request class.
+ *
+ * ```ts
+ * @ListOptions({ defaultSize: 20, maxSize: 100, include: ["posts"] })
+ * class UserListQuery extends ListRequest<User> { ... }
+ * ```
+ */
+export function ListOptions(config: ListOptionsConfig) {
+  return (_value: unknown, context: ClassDecoratorContext): void => {
+    const schema = ensureOwnSchema(context.metadata as SchemaMetadata);
+    schema.page = { defaultSize: config.defaultSize, maxSize: config.maxSize };
+    if (config.include !== undefined) {
+      schema.include = config.include;
+    }
+  };
+}
+
+/** Schema of a request class (including the inherited one), or `undefined`. */
+export function listSchemaOf(ctor: unknown): ListSchema | undefined {
+  if (typeof ctor !== "function") {
+    return undefined;
+  }
+  const metadata = (ctor as unknown as { [key: symbol]: unknown })[Symbol.metadata as symbol] as
+    | SchemaMetadata
+    | undefined;
+  return metadata?.[LIST_SCHEMA];
+}
+
+/**
+ * Builds {@link ListQueryOptions} (the allow list for {@link parseListQuery})
+ * from the declarative schema of a request class.
+ */
+export function optionsFromSchema(ctor: unknown): ListQueryOptions {
+  const schema = listSchemaOf(ctor);
+  if (schema === undefined) {
+    return {};
+  }
+  const sort: string[] = [];
+  const filter: Record<string, readonly FilterOperator[]> = {};
+  for (const [name, field] of Object.entries(schema.fields)) {
+    if (field.sortable) {
+      sort.push(name);
+    }
+    if (field.filterOps.length > 0) {
+      filter[name] = field.filterOps;
+    }
+  }
+  return { sort, filter, include: schema.include, page: schema.page };
+}

package/library/jsonapi/document.ts

@@ -0,0 +1,124 @@
+import type { ListQuery } from "./types";
+
+/** Collection metadata (page counters), put into the response `meta`. */
+export interface ListMeta {
+  /** Total number of records with filters applied (without paging). */
+  readonly total: number;
+  /** Current page number (1-based). */
+  readonly page: number;
+  /** Page size. */
+  readonly size: number;
+  /** Total pages = `ceil(total / size)`. */
+  readonly pageCount: number;
+}
+
+/** JSON:API-style paging links (`links`). */
+export interface ListLinks {
+  readonly self: string;
+  readonly first: string;
+  readonly last: string;
+  readonly prev?: string;
+  readonly next?: string;
+}
+
+/**
+ * Collection response document. `data` holds the items (entities or DTOs),
+ * `meta` the counters, `links` the page navigation (if `basePath` is set).
+ */
+export interface ListDocument<T> {
+  readonly data: readonly T[];
+  readonly meta: ListMeta;
+  readonly links?: ListLinks;
+}
+
+/** Options for building a {@link ListDocument}. */
+export interface BuildListDocumentOptions {
+  /**
+   * Base path for paging links, for example `"/api/users"`. If not set,
+   * `links` are not built.
+   */
+  readonly basePath?: string;
+}
+
+/**
+ * Builds a JSON:API-like collection document from the page items, the original
+ * request and the total number of records.
+ *
+ * ```ts
+ * const { items, total } = await paginate(repo.query(), query);
+ * return buildListDocument(items, query, total, { basePath: "/api/users" });
+ * ```
+ */
+export function buildListDocument<T>(
+  items: readonly T[],
+  query: ListQuery,
+  total: number,
+  options: BuildListDocumentOptions = {},
+): ListDocument<T> {
+  const size = query.page.size;
+  const pageCount = size > 0 ? Math.max(1, Math.ceil(total / size)) : 1;
+  const meta: ListMeta = { total, page: query.page.number, size, pageCount };
+
+  if (options.basePath === undefined) {
+    return { data: items, meta };
+  }
+  return { data: items, meta, links: buildLinks(query, options.basePath, meta) };
+}
+
+/**
+ * Serializes the request into a JSON:API query string (without the leading `?`).
+ * Useful for building links and for round trips in tests.
+ */
+export function serializeListQuery(query: ListQuery, pageNumber?: number): string {
+  return toSearchParams(query, pageNumber).toString();
+}
+
+function buildLinks(query: ListQuery, basePath: string, meta: ListMeta): ListLinks {
+  const link = (page: number): string => `${basePath}?${serializeListQuery(query, page)}`;
+  const links: ListLinks = {
+    self: link(meta.page),
+    first: link(1),
+    last: link(meta.pageCount),
+    ...(meta.page > 1 ? { prev: link(meta.page - 1) } : {}),
+    ...(meta.page < meta.pageCount ? { next: link(meta.page + 1) } : {}),
+  };
+  return links;
+}
+
+function toSearchParams(query: ListQuery, pageNumber?: number): URLSearchParams {
+  const params = new URLSearchParams();
+
+  if (query.sort.length > 0) {
+    params.set("sort", query.sort.map((s) => `${s.dir === "desc" ? "-" : ""}${s.field}`).join(","));
+  }
+
+  for (const rule of query.filters) {
+    const key = rule.op === "eq" ? `filter[${rule.field}]` : `filter[${rule.field}][${rule.op}]`;
+    const value = Array.isArray(rule.value) ? rule.value.join(",") : (rule.value as string);
+    params.append(key, value);
+  }
+
+  query.or.forEach((group, index) => {
+    for (const rule of group) {
+      const key =
+        rule.op === "eq"
+          ? `filter[or][${index}][${rule.field}]`
+          : `filter[or][${index}][${rule.field}][${rule.op}]`;
+      const value = Array.isArray(rule.value) ? rule.value.join(",") : (rule.value as string);
+      params.append(key, value);
+    }
+  });
+
+  params.set("page[number]", String(pageNumber ?? query.page.number));
+  params.set("page[size]", String(query.page.size));
+
+  if (query.include.length > 0) {
+    params.set("include", query.include.join(","));
+  }
+  for (const [type, list] of Object.entries(query.fields)) {
+    if (list.length > 0) {
+      params.set(`fields[${type}]`, list.join(","));
+    }
+  }
+  return params;
+}

package/library/jsonapi/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Universal list request in the style of the JSON:API specification.
+ *
+ * A pure library (Web APIs only, zero dependencies on the kernel/environment),
+ * compatible with binary compilation. It consists of:
+ * - {@link parseListQuery}: parses query parameters (`sort`/`filter`/`page`/
+ *   `include`/`fields`) into a typed, validated {@link ListQuery};
+ * - {@link buildListDocument}: builds the collection response (`data`/`meta`/`links`);
+ * - {@link ListQueryError}: the parsing error (the HTTP layer maps it to 400).
+ *
+ * Applying the request to a data source is a separate integration layer:
+ * the ORM bridge is `paginate(...)` in `@/core/orm`, the binding is `ListRequest`
+ * in `@/core/http`.
+ */
+export { parseListQuery } from "./parseListQuery";
+export { buildListDocument, serializeListQuery } from "./document";
+export type { BuildListDocumentOptions, ListDocument, ListLinks, ListMeta } from "./document";
+export { ListQueryError, type ListQueryProblem } from "./ListQueryError";
+export { ListRequest } from "./ListRequest";
+export {
+  Filterable,
+  ListOptions,
+  Sortable,
+  listSchemaOf,
+  optionsFromSchema,
+  type FieldSchema,
+  type ListOptionsConfig,
+  type ListSchema,
+} from "./decorators";
+export type {
+  FilterGroup,
+  FilterOperator,
+  FilterRule,
+  ListQuery,
+  ListQueryOptions,
+  PageOptions,
+  PageParams,
+  SortDirection,
+  SortField,
+} from "./types";

package/library/jsonapi/parseListQuery.ts

@@ -0,0 +1,291 @@
+import { ListQueryError, type ListQueryProblem } from "./ListQueryError";
+import type {
+  FilterGroup,
+  FilterOperator,
+  FilterRule,
+  ListQuery,
+  ListQueryOptions,
+  PageParams,
+  SortDirection,
+  SortField,
+} from "./types";
+
+const DEFAULT_PAGE_SIZE = 20;
+const MAX_PAGE_SIZE = 100;
+
+const FILTER_OPERATORS: ReadonlySet<string> = new Set<FilterOperator>([
+  "eq",
+  "ne",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "like",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "in",
+  "nin",
+  "isNull",
+  "isNotNull",
+]);
+
+const VALUELESS_OPERATORS: ReadonlySet<FilterOperator> = new Set(["isNull", "isNotNull"]);
+const MULTI_VALUE_OPERATORS: ReadonlySet<FilterOperator> = new Set(["in", "nin"]);
+
+/** `filter[field]` or `filter[field][op]`. */
+const FILTER_KEY = /^filter\[([^\]]+)\](?:\[([^\]]+)\])?$/;
+/** `filter[or][N][field]` or `filter[or][N][field][op]` (N is the OR group index). */
+const FILTER_OR_KEY = /^filter\[or\]\[(\d+)\]\[([^\]]+)\](?:\[([^\]]+)\])?$/;
+/** `fields[type]`. */
+const FIELDS_KEY = /^fields\[([^\]]+)\]$/;
+
+/**
+ * Parses JSON:API-style query parameters into a typed {@link ListQuery}.
+ *
+ * Secure by default: sorting/filtering/include are allowed only for fields
+ * from {@link ListQueryOptions}; anything else produces a {@link ListQueryError}
+ * (with the list of all problems at once).
+ *
+ * ```ts
+ * const query = parseListQuery(url.searchParams, {
+ *   sort: ["name", "createdAt"],
+ *   filter: { age: ["gte", "lte"], name: ["contains"] },
+ *   page: { defaultSize: 20, maxSize: 100 },
+ * });
+ * ```
+ */
+export function parseListQuery(params: URLSearchParams, options: ListQueryOptions = {}): ListQuery {
+  const problems: ListQueryProblem[] = [];
+
+  const sort = parseSort(params, options, problems);
+  const filters = parseFilters(params, options, problems);
+  const or = parseOrGroups(params, options, problems);
+  const page = parsePage(params, options, problems);
+  const include = parseInclude(params, options, problems);
+  const fields = parseFields(params);
+
+  if (problems.length > 0) {
+    throw new ListQueryError(problems);
+  }
+  return { sort, filters, or, page, include, fields };
+}
+
+function parseSort(
+  params: URLSearchParams,
+  options: ListQueryOptions,
+  problems: ListQueryProblem[],
+): SortField[] {
+  const result: SortField[] = [];
+  for (const token of splitCsv(params.getAll("sort"))) {
+    const dir: SortDirection = token.startsWith("-") ? "desc" : "asc";
+    const field = token.replace(/^[-+]/, "");
+    if (field === "") {
+      problems.push({ parameter: "sort", message: `empty sort field in "${token}"` });
+      continue;
+    }
+    if (!options.sort?.includes(field)) {
+      problems.push({ parameter: "sort", message: `sorting by "${field}" is not allowed` });
+      continue;
+    }
+    result.push({ field, dir });
+  }
+  return result;
+}
+
+function parseFilters(
+  params: URLSearchParams,
+  options: ListQueryOptions,
+  problems: ListQueryProblem[],
+): FilterRule[] {
+  const result: FilterRule[] = [];
+  for (const [key, rawValue] of params) {
+    const match = FILTER_KEY.exec(key);
+    if (!match) {
+      continue;
+    }
+    const field = match[1]!;
+    const opToken = match[2] ?? "eq";
+    const parameter = match[2] ? `filter[${field}][${opToken}]` : `filter[${field}]`;
+    const rule = parseFilterLeaf(field, opToken, rawValue, parameter, options, problems);
+    if (rule !== undefined) {
+      result.push(rule);
+    }
+  }
+  return result;
+}
+
+/**
+ * Parses OR groups `filter[or][N][field][op]=v`. Conditions with the same `N`
+ * form a group (AND); groups are returned in ascending `N` order (different
+ * groups are OR). Each leaf is validated against the same allow list as the
+ * top-level filters.
+ */
+function parseOrGroups(
+  params: URLSearchParams,
+  options: ListQueryOptions,
+  problems: ListQueryProblem[],
+): FilterGroup[] {
+  const groups = new Map<number, FilterRule[]>();
+  for (const [key, rawValue] of params) {
+    const match = FILTER_OR_KEY.exec(key);
+    if (!match) {
+      continue;
+    }
+    const index = Number(match[1]);
+    const field = match[2]!;
+    const opToken = match[3] ?? "eq";
+    const parameter = match[3]
+      ? `filter[or][${index}][${field}][${opToken}]`
+      : `filter[or][${index}][${field}]`;
+    const rule = parseFilterLeaf(field, opToken, rawValue, parameter, options, problems);
+    if (rule !== undefined) {
+      const group = groups.get(index) ?? [];
+      group.push(rule);
+      groups.set(index, group);
+    }
+  }
+  return [...groups.keys()].sort((a, b) => a - b).map((key) => groups.get(key)!);
+}
+
+/** Parses and validates one filter condition (`field`/`op`/`value`). */
+function parseFilterLeaf(
+  field: string,
+  opToken: string,
+  rawValue: string,
+  parameter: string,
+  options: ListQueryOptions,
+  problems: ListQueryProblem[],
+): FilterRule | undefined {
+  if (!FILTER_OPERATORS.has(opToken)) {
+    problems.push({ parameter, message: `unknown filter operator "${opToken}"` });
+    return undefined;
+  }
+  const op = opToken as FilterOperator;
+
+  const allowedOps = options.filter?.[field];
+  if (!allowedOps) {
+    problems.push({ parameter, message: `filtering by "${field}" is not allowed` });
+    return undefined;
+  }
+  if (!allowedOps.includes(op)) {
+    problems.push({ parameter, message: `operator "${op}" is not allowed for "${field}"` });
+    return undefined;
+  }
+
+  if (VALUELESS_OPERATORS.has(op)) {
+    return { field, op, value: "" };
+  }
+  if (MULTI_VALUE_OPERATORS.has(op)) {
+    const values = rawValue
+      .split(",")
+      .map((value) => value.trim())
+      .filter((value) => value !== "");
+    if (values.length === 0) {
+      problems.push({ parameter, message: `operator "${op}" needs a non-empty comma-separated list` });
+      return undefined;
+    }
+    return { field, op, value: values };
+  }
+  return { field, op, value: rawValue };
+}
+
+function parsePage(
+  params: URLSearchParams,
+  options: ListQueryOptions,
+  problems: ListQueryProblem[],
+): PageParams {
+  const maxSize = options.page?.maxSize ?? MAX_PAGE_SIZE;
+  const defaultSize = clamp(options.page?.defaultSize ?? DEFAULT_PAGE_SIZE, 1, maxSize);
+
+  const requestedSize = parsePositiveInt(params.get("page[size]") ?? params.get("page[limit]"), "page[size]", problems);
+  const size = requestedSize === undefined ? defaultSize : clamp(requestedSize, 1, maxSize);
+
+  const offsetRaw = params.get("page[offset]");
+  if (offsetRaw !== null && offsetRaw !== "") {
+    const offset = parseNonNegativeInt(offsetRaw, "page[offset]", problems) ?? 0;
+    return { number: Math.floor(offset / size) + 1, size, offset, limit: size };
+  }
+
+  const number = parsePositiveInt(params.get("page[number]"), "page[number]", problems) ?? 1;
+  return { number, size, offset: (number - 1) * size, limit: size };
+}
+
+function parseInclude(
+  params: URLSearchParams,
+  options: ListQueryOptions,
+  problems: ListQueryProblem[],
+): string[] {
+  const result: string[] = [];
+  for (const path of splitCsv(params.getAll("include"))) {
+    if (!options.include?.includes(path)) {
+      problems.push({ parameter: "include", message: `include "${path}" is not allowed` });
+      continue;
+    }
+    result.push(path);
+  }
+  return result;
+}
+
+function parseFields(params: URLSearchParams): Record<string, readonly string[]> {
+  const fields: Record<string, string[]> = {};
+  for (const [key, value] of params) {
+    const match = FIELDS_KEY.exec(key);
+    if (!match) {
+      continue;
+    }
+    const type = match[1]!;
+    const list = value
+      .split(",")
+      .map((item) => item.trim())
+      .filter((item) => item !== "");
+    fields[type] = (fields[type] ?? []).concat(list);
+  }
+  return fields;
+}
+
+function splitCsv(values: readonly string[]): string[] {
+  const tokens: string[] = [];
+  for (const value of values) {
+    for (const token of value.split(",")) {
+      const trimmed = token.trim();
+      if (trimmed !== "") {
+        tokens.push(trimmed);
+      }
+    }
+  }
+  return tokens;
+}
+
+function parsePositiveInt(
+  raw: string | null,
+  parameter: string,
+  problems: ListQueryProblem[],
+): number | undefined {
+  if (raw === null || raw === "") {
+    return undefined;
+  }
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1) {
+    problems.push({ parameter, message: "must be a positive integer" });
+    return undefined;
+  }
+  return value;
+}
+
+function parseNonNegativeInt(
+  raw: string,
+  parameter: string,
+  problems: ListQueryProblem[],
+): number | undefined {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    problems.push({ parameter, message: "must be a non-negative integer" });
+    return undefined;
+  }
+  return value;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}