@kalutskii/foundation 0.1.3

package/README.md

@@ -0,0 +1,125 @@
+# @esb-market-contracts/core
+
+Shared HTTP contracts and helpers for consistent API communication across esb-market-space services.
+
+## What this package provides
+
+- Typed API response contracts.
+- Response factories for success and failure payloads.
+- Safe async resolvers for contract-based fetch functions.
+- A Hono helper for typed JSON success responses.
+- Utility types/helpers for query parsing and Date serialization.
+
+## Installation
+
+```bash
+bun add @esb-market-contracts/core
+```
+
+or
+
+```bash
+npm i @esb-market-contracts/core
+```
+
+## Core concepts
+
+Contract shape:
+
+- Success: `{ kind: 'data', status, data }`
+- Error: `{ kind: 'error', status, error }`
+
+Status code groups are exported as constants and used by types:
+
+- `SUCCESS_STATUS_CODES`
+- `EXCEPTION_STATUS_CODES`
+
+## Usage
+
+### 1. Build typed contracts
+
+```ts
+import { failure, success } from '@esb-market-contracts/core';
+import type { APIContractResult } from '@esb-market-contracts/core';
+
+type User = { id: string; name: string };
+
+const ok = success<User>({ status: 200, data: { id: '1', name: 'Kate' } });
+const bad = failure({ status: 404, error: 'User not found' });
+
+const result: APIContractResult<User> = Math.random() > 0.5 ? ok : bad;
+```
+
+### 2. Resolve fetchers safely
+
+```ts
+import { fetchAndThrow, fetchSafely } from '@esb-market-contracts/core';
+import type { APIContractResult } from '@esb-market-contracts/core';
+
+type User = { id: string; name: string };
+
+declare function getUser(): Promise<APIContractResult<User>>;
+
+const safe = await fetchSafely(getUser);
+if (safe.error) {
+  console.error(safe.error.message);
+} else {
+  console.log(safe.data.name);
+}
+
+try {
+  const user = await fetchAndThrow(getUser);
+  console.log(user.name);
+} catch (error) {
+  console.error(error);
+}
+```
+
+### 3. Use typed Hono JSON responses
+
+```ts
+import { respond } from '@esb-market-contracts/core';
+import { Hono } from 'hono';
+
+const app = new Hono();
+
+app.get('/health', (c) => {
+  return respond(c, {
+    status: 200,
+    data: { ok: true, now: new Date() },
+  });
+});
+```
+
+`respond` returns a typed JSON response contract and includes API error type in route output unions.
+
+### 4. Parse query params with helpers
+
+```ts
+import { asQueryBoolean, asQueryNumber } from '@esb-market-contracts/core';
+import { z } from 'zod';
+
+const pageSchema = asQueryNumber(z.number().int().min(1));
+const enabledSchema = asQueryBoolean(z.boolean());
+
+pageSchema.parse('2'); // 2
+enabledSchema.parse('yes'); // true
+enabledSchema.parse('off'); // false
+```
+
+## Exports
+
+The package exports all public APIs from a single entrypoint:
+
+- HTTP constants, schemas, factories, and resolvers.
+- Hono `respond` helper.
+- Serialization/query utilities, including `SerializeDates`.
+
+## Development
+
+```bash
+bun install
+bun run lint
+bun run typecheck
+bun run build
+```

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+import { Context, TypedResponse } from 'hono';
+import { z, ZodNumber } from 'zod';
+
+declare const SUCCESS_STATUS_CODES: readonly [200, 201, 202, 307];
+declare const EXCEPTION_STATUS_CODES: readonly [400, 401, 403, 404, 405, 409, 500];
+
+type SuccessStatusCode = (typeof SUCCESS_STATUS_CODES)[number];
+type ExceptionStatusCode = (typeof EXCEPTION_STATUS_CODES)[number];
+type APISuccess<T = void> = {
+    kind: 'data';
+    status: SuccessStatusCode;
+    data: T;
+};
+type APIError = {
+    kind: 'error';
+    status: ExceptionStatusCode;
+    error: string;
+};
+type APIContractResult<TData = void> = APISuccess<TData> | APIError;
+type APIContractData<TResult extends APIContractResult<unknown>> = TResult extends APISuccess<infer TData> ? TData : never;
+type APIContractError<TResult extends APIContractResult<unknown>> = Extract<TResult, APIError>;
+/** Discriminated union result of a fetch operation. If `error` is set, `data` is null and vice versa. */
+type FetchResult<T> = {
+    error: null;
+    data: T;
+} | {
+    error: Error;
+    data: null;
+};
+
+/** Factory for creating successful API responses with serializable data. */
+declare function success<T = unknown>({ status, data }: {
+    status: SuccessStatusCode;
+    data: T;
+}): APISuccess<T>;
+/** Factory for creating API error responses, including the error message. */
+declare function failure({ status, error }: {
+    status: ExceptionStatusCode;
+    error: string;
+}): APIError;
+
+/** Resolves an APIContractResult fetcher into a FetchResult discriminated union. */
+declare function fetchSafely<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<FetchResult<APIContractData<TResult>>>;
+/** Resolves an APIContractResult fetcher, throwing an error if the result is an APIError. */
+declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<APIContractData<TResult>>;
+
+/**
+ * Type utility that recursively transforms all Date fields to string, as well as handling arrays and objects.
+ * This is necessary for proper typing when working with RPC, as JSON does not support the Date type directly.
+ * Example: SerializeDates<{ createdAt: Date; nested: { updatedAt: Date }; tags: Date[] }> \
+ * = { createdAt: string; nested: { updatedAt: string }; tags: string[] }
+ */
+type SerializeDates<T> = T extends Date ? string : T extends (infer U)[] ? SerializeDates<U>[] : T extends readonly (infer U)[] ? readonly SerializeDates<U>[] : T extends object ? {
+    [K in keyof T]: SerializeDates<T[K]>;
+} : T;
+/**
+ * Transforms a string to a number (when passing query parameters).
+ * Example: asQueryNumber(z.number())('123') = 123
+ */
+declare const asQueryNumber: <T extends ZodNumber>(schema: T) => z.ZodPreprocess<T>;
+/**
+ * Transforms various string representations of boolean values into actual booleans.
+ * See POSITIVE_VALUES and NEGATIVE_VALUES arrays below for supported inputs.
+ */
+declare const asQueryBoolean: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<T>;
+
+/**
+ * Wraps c.json with a typed success payload & possible APIError.
+ * When no data is provided, responds with an empty object {}.
+ */
+declare function respond<T extends object = Record<string, never>, S extends SuccessStatusCode = SuccessStatusCode>(c: Context, options: {
+    status: S;
+    data?: T;
+}): Response & TypedResponse<APISuccess<SerializeDates<T>> | APIError, S, 'json'>;
+
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, SUCCESS_STATUS_CODES, type SerializeDates, type SuccessStatusCode, asQueryBoolean, asQueryNumber, failure, fetchAndThrow, fetchSafely, respond, success };

package/dist/index.js

@@ -0,0 +1,61 @@
+// src/http/http.constants.ts
+var SUCCESS_STATUS_CODES = [200, 201, 202, 307];
+var EXCEPTION_STATUS_CODES = [400, 401, 403, 404, 405, 409, 500];
+
+// src/http/http.factory.ts
+function success({ status, data }) {
+  return { kind: "data", status, data };
+}
+function failure({ status, error }) {
+  return { kind: "error", status, error };
+}
+
+// src/http/http.resolvers.ts
+async function fetchSafely(fetcher) {
+  const response = await fetcher();
+  if (response.kind === "error")
+    return { error: new Error(response.error), data: null };
+  return { error: null, data: response.data };
+}
+async function fetchAndThrow(fetcher) {
+  const response = await fetcher();
+  if (response.kind === "error")
+    throw new Error(response.error);
+  return response.data;
+}
+
+// src/hono/hono.respond.ts
+function respond(c, options) {
+  return c.json(success({ status: options.status, data: options.data ?? {} }), options.status);
+}
+
+// src/utilities/serialize.utilities.ts
+import { z } from "zod";
+var asQueryNumber = (schema) => z.preprocess((v) => typeof v === "string" ? Number(v) : v, schema);
+var asQueryBoolean = (schema) => {
+  const POSITIVE_VALUES = ["1", "true", "yes", "y", "on"];
+  const NEGATIVE_VALUES = ["0", "false", "no", "n", "off"];
+  return z.preprocess((value) => {
+    if (typeof value === "boolean")
+      return value;
+    if (typeof value === "string") {
+      const normalized = value.trim().toLowerCase();
+      if (POSITIVE_VALUES.includes(normalized))
+        return true;
+      if (NEGATIVE_VALUES.includes(normalized))
+        return false;
+    }
+    return value;
+  }, schema);
+};
+export {
+  EXCEPTION_STATUS_CODES,
+  SUCCESS_STATUS_CODES,
+  asQueryBoolean,
+  asQueryNumber,
+  failure,
+  fetchAndThrow,
+  fetchSafely,
+  respond,
+  success
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kalutskii/foundation",
+  "version": "0.1.3",
+  "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kalutskii/foundation.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "date-fns": "^4.1.0",
+    "date-fns-tz": "^3.2.0",
+    "hono": "^4.12.18",
+    "kleur": "^4.1.5",
+    "typescript": "^5",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/bun": "latest",
+    "esbuild-plugin-tsconfig-paths": "^1.0.2",
+    "eslint": "^10.2.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "typescript-eslint": "^8.58.2"
+  }
+}