@ololoepepe/controllers 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-29
+
+### Changed
+
+- `Json` accepts readonly arrays: the array member is now `readonly Json[]`. A
+  `ReadonlyArray` field, or anything produced by `as const`, could not be a response
+  body, because a readonly array is not assignable to a mutable one. Mutable arrays are
+  unaffected — they are assignable to readonly ones, so every body that compiled before
+  still compiles.
+
+  Breaking only for code that passes a value typed `Json` on to a JSON type declaring
+  its arrays mutable — another library's `JsonValue`, or a copy of this one. The same
+  goes for `Extract<Json, unknown[]>`, which now resolves to `never` and fails at the
+  use site rather than where it is declared.
+
+## [0.4.0] - 2026-08-28
+
+### Changed
+
+- `JsonResponse` takes the body as a type parameter constrained to `Json` instead of
+  `unknown`, and `jsonController` gained a matching third parameter, inferred from the
+  callback. The body of a JSON response was typed `unknown`, so `json(undefined)`
+  type-checked even though `undefined` is not a JSON value. Also rejected are `bigint`
+  (`JSON.stringify` throws on it), `symbol` and functions, nested fields included.
+
+  A callback that returns nothing still sends the empty object, which is what
+  `EmptyJsonBody` names, so a response has to admit it alongside its own body type —
+  `JsonResponse<EmptyJsonBody | Tenant>`. `null` is unaffected: it is a JSON value and
+  goes out as it is.
+
+  Response bodies now have to be declared with `type` rather than `interface`:
+  TypeScript assigns no `interface` to a type with an index signature, which `Json`
+  rests on.
+
+  Breaking for code that names `JsonResponse` explicitly; the type argument is now
+  required. Code that only passes callbacks is unaffected.
+
+### Added
+
+- Exported types `Json` and `EmptyJsonBody`.
+
 ## [0.3.0] - 2026-08-28
 
 ### Changed

package/README.md

@@ -149,17 +149,62 @@ The request and the response are type parameters, defaulting to Express's
 your own shapes — the controllers only require what they actually use:
 
 ```ts
-import {jsonController, type ControllerRequest, type JsonResponse} from '@ololoepepe/controllers';
+import {
+  jsonController,
+  type ControllerRequest,
+  type EmptyJsonBody,
+  type JsonResponse
+} from '@ololoepepe/controllers';
+
+type Tenant = {
+  id: string;
+  name: string;
+};
 
 interface TenantRequest extends ControllerRequest {
   tenantId: string;
 }
 
-const controller = jsonController<TenantRequest, JsonResponse>(request => loadTenant(request.tenantId));
+const controller = jsonController<TenantRequest, JsonResponse<EmptyJsonBody | Tenant>, Tenant>(
+  request => loadTenant(request.tenantId)
+);
 ```
 
+`jsonController` has a third parameter for the body, inferred from the callback,
+so you only name it when you name the response as well. It is constrained to
+`Json` — what JSON can actually hold:
+
+```ts
+export type Json = boolean | null | number | readonly Json[] | string | {[key: string]: Json};
+```
+
+That rules out `undefined`, `bigint` (`JSON.stringify` throws on it), `symbol`
+and functions, and it checks nested fields too.
+
+Arrays are `readonly`, so a `ReadonlyArray` field or an `as const` value can be a
+body. A mutable array still passes, being assignable to a readonly one.
+
+**Describe response bodies with `type`, not `interface`.** TypeScript does not
+assign an `interface` to a type with an index signature, so an interface will not
+satisfy `Json` however JSON-shaped it is — including one nested inside a `type`:
+
+```ts
+interface Tenant {id: string}   // will not compile as a body
+type Tenant = {id: string};     // will
+```
+
+`Date` does not satisfy `Json` either. Say `string`, which is what a date is by
+the time it reaches the client anyway — `JSON.stringify` calls `toJSON` on it.
+Optional properties are fine: `type Tenant = {id: string; note?: string}` passes.
+
+The callback may still return `undefined`; that is the documented "no body" case,
+and what goes out instead is the empty object `EmptyJsonBody`. This is why the
+response above has to accept `EmptyJsonBody | Tenant` rather than just `Tenant`.
+`null` is left alone, being a JSON value like any other.
+
 Exported types: `Controller`, `ControllerCallback`, `ControllerRequest`,
-`JsonResponse`, `NextFunction`, `NoContentResponse`, `StringResponse`.
+`EmptyJsonBody`, `Json`, `JsonResponse`, `NextFunction`, `NoContentResponse`,
+`StringResponse`.
 
 ## Development
 

package/dist/node/controllers/json-controller.d.ts

@@ -1,5 +1,5 @@
 import type { Request, Response } from 'express';
-import type { Controller, ControllerCallback, ControllerRequest, JsonResponse } from '#src/types.ts';
+import type { Controller, ControllerCallback, ControllerRequest, EmptyJsonBody, Json, JsonResponse } from '#src/types.ts';
 /**
  * Создает контроллер, который вызывает `callback` на каждый запрос и отправляет его результат
  * в виде JSON.
@@ -14,4 +14,4 @@ import type { Controller, ControllerCallback, ControllerRequest, JsonResponse }
  * @param callback - функция, вызываемая на входящий запрос
  * @param statusCode - код ответа, если нужен не тот, что выбирается по методу запроса
  */
-export default function jsonController<TRequest extends ControllerRequest = Request, TResponse extends JsonResponse = Response>(callback: ControllerCallback<TRequest, TResponse>, statusCode?: number): Controller<TRequest, TResponse>;
+export default function jsonController<TRequest extends ControllerRequest = Request, TResponse extends JsonResponse<EmptyJsonBody | TBody> = Response, TBody extends Json = EmptyJsonBody>(callback: ControllerCallback<TRequest, TResponse, TBody | undefined>, statusCode?: number): Controller<TRequest, TResponse>;

package/dist/node/controllers/json-controller.js

@@ -17,7 +17,10 @@ export default function jsonController(callback, statusCode) {
     return async (request, response, next) => {
         try {
             const result = await callback(request, response);
-            // Пустым объектом подменяется только `undefined`: `null` — осмысленное тело ответа
+            // Подменяется только `undefined`: значения `undefined` в JSON нет, а `null` — осмысленное
+            // тело ответа. Правило считает эту тернарку равнозначной `??`, потому что не видит `null`
+            // внутри свободного параметра `TBody`, но `??` подменил бы и его.
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- `??` подменил бы и `null`
             const body = (result === undefined) ? {} : result;
             response.status(statusCode ?? selectStatusCode(request.method)).json(body);
         }

package/dist/node/index.d.ts

@@ -1,2 +1,2 @@
 export { jsonController, noContentController, stringController } from '#src/controllers/index.ts';
-export type { Controller, ControllerCallback, ControllerRequest, JsonResponse, NextFunction, NoContentResponse, StringResponse } from '#src/types.ts';
+export type { Controller, ControllerCallback, ControllerRequest, EmptyJsonBody, Json, JsonResponse, NextFunction, NoContentResponse, StringResponse } from '#src/types.ts';

package/dist/node/types.d.ts

@@ -11,10 +11,31 @@ export type NextFunction = (error?: unknown) => void;
 export interface ControllerRequest {
     method: string;
 }
+/**
+ * Значение, которое можно отдать в JSON.
+ *
+ * Того, чего в JSON нет, здесь и не перечислено: `undefined`, `bigint` (на нем `JSON.stringify`
+ * падает), `symbol` и функция телом ответа стать не смогут.
+ *
+ * У объектов проверяются и поля, вглубь. Цена этого в том, что TypeScript не присваивает
+ * `interface` типу с индексной сигнатурой, поэтому тело ответа описывается через `type`, а не
+ * через `interface`.
+ *
+ * Массив взят `readonly`, чтобы телом ответа могли стать `ReadonlyArray` и результат `as const`.
+ * Изменяемый массив подходит и так: он присваивается в `readonly`, обратное неверно.
+ */
+export type Json = boolean | null | number | readonly Json[] | string | {
+    [key: string]: Json;
+};
+/**
+ * Тело, которое контроллер отправляет вместо `undefined`: значения `undefined` в JSON нет,
+ * поэтому вместо него уходит пустой объект.
+ */
+export type EmptyJsonBody = Record<string, never>;
 /** Ответ, умеющий отдать тело в виде JSON. */
-export interface JsonResponse {
+export interface JsonResponse<TBody extends Json> {
     status: (statusCode: number) => {
-        json: (body: unknown) => unknown;
+        json: (body: TBody) => unknown;
     };
 }
 /** Ответ, умеющий отдать тело в виде строки. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ololoepepe/controllers",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Common Express controllers library",
   "type": "module",
   "imports": {