@kalutskii/foundation 0.6.19 → 0.6.21

package/README.md

@@ -42,7 +42,7 @@ Status code groups are exported as constants and used by types:
 
 ### 1. Build typed contracts
 
-```ts
+```typescript
 import { failure, success } from '@kalutskii/foundation';
 import type { APIContractResult } from '@kalutskii/foundation';
 
@@ -56,7 +56,7 @@ const result: APIContractResult<User> = Math.random() > 0.5 ? ok : bad;
 
 ### 2. Resolve fetchers safely
 
-```ts
+```typescript
 import { fetchAndThrow, fetchSafely } from '@kalutskii/foundation';
 import type { APIContractResult } from '@kalutskii/foundation';
 
@@ -81,7 +81,7 @@ try {
 
 ### 3. Use typed Hono JSON responses
 
-```ts
+```typescript
 import { respond } from '@kalutskii/foundation';
 import { Hono } from 'hono';
 
@@ -99,7 +99,7 @@ app.get('/health', (c) => {
 
 ### 4. Wire up Hono error handler and logging middleware
 
-```ts
+```typescript
 import { honoLoggingHandler, onHandlerError } from '@kalutskii/foundation';
 import { Hono } from 'hono';
 
@@ -116,7 +116,7 @@ Example: `[12:12:12 (+4 UTC)] hono         | POST 200    123ms /api/v1/users (se
 
 ### 5. Execute functions safely and measure performance
 
-```ts
+```typescript
 import { measureExecutionTime, safeExecute } from '@kalutskii/foundation';
 
 const result = await safeExecute(
@@ -130,7 +130,7 @@ console.log(`Done in ${executionTime}ms`);
 
 ### 6. Parse query params with `asQuery`
 
-```ts
+```typescript
 import { asQuery } from '@kalutskii/foundation';
 import { z } from 'zod';
 
@@ -146,7 +146,7 @@ schema.parse({ page: '2', isActive: 'true' }); // { page: 2, isActive: true }
 
 ### 8. Build flat query schemas from nested objects
 
-```ts
+```typescript
 import { asQuerySchema } from '@kalutskii/foundation';
 import { z } from 'zod';
 
@@ -173,7 +173,7 @@ schema.parse({ sort: { field: 'name', order: 'asc' } }); // throws
 
 ### 8. Use pagination schema
 
-```ts
+```typescript
 import { refinePagination, zodPaginationSchema, zodPaginationShape } from '@kalutskii/foundation';
 import { z } from 'zod';
 
@@ -195,7 +195,7 @@ await db.query.users.findMany({
 
 ### 9. Work with JWT using `ZodJWTService`
 
-```ts
+```typescript
 import { ZodJWTService } from '@kalutskii/foundation';
 import { z } from 'zod';
 
@@ -212,7 +212,7 @@ const decoded = await jwt.decode(token);
 
 ### 10. Datetime helpers
 
-```ts
+```typescript
 import { formatTime, getFormattedDate, getFormattedTime, getZonedTime } from '@kalutskii/foundation';
 
 getFormattedTime({ tz: 'Europe/Moscow' }); // '15:30:00 (+3 UTC)'
@@ -223,7 +223,7 @@ formatTime(new Date(), { tz: 'Europe/Moscow' }); // '15:30:00, 22 июня 2026
 
 ### 11. Logging
 
-```ts
+```typescript
 import { log } from '@kalutskii/foundation';
 
 log.info('Server started', 'app');

package/dist/index.d.ts

@@ -10,7 +10,7 @@ import z, { ZodObject, ZodRawShape, z as z$1 } from 'zod';
  * Maps each `where` entry to `eq(table[key], value)` and combines them with `and`.
  * Assumes that `where` was already validated and contains only existing table fields.
  *
- * ```ts
+ * ```typescript
  * await db.update(usersTable).set(values).where(sqlWhere(usersTable, { id: 1 })).returning();
  * ```
  */
@@ -73,7 +73,7 @@ type AsQuery<T> = T extends null | undefined ? T : T extends QueryPrimitive ? st
  * This is useful for scenarios where you want to enforce that at least one
  * of several optional (nullable) properties must be provided in an object.
  *
- * ```ts
+ * ```typescript
  * type Example = AtLeastOne<{ a?: string; b?: number; c?: boolean }>;
  * // Valid: { a: "hello" }, { b: 42 }, { c: true }, { a: "hello", b: 42 }
  * // Invalid: {}, { a: undefined, b: undefined, c: undefined }
@@ -174,6 +174,24 @@ declare const formatTime: (time: Date, { locale, tz }?: {
     tz?: string;
 }) => string;
 
+/**
+ * Recursively replaces dots in a string with underscores in a type-safe manner.
+ * Example: `ReplaceDotsWithUnderscores<'foo.bar.baz.ok'>` → `'foo_bar_baz_ok'`.
+ */
+type ReplaceDotsWithUnderscores<T extends string> = T extends `${infer A}.${infer B}` ? `${A}_${ReplaceDotsWithUnderscores<B>}` : T;
+/**
+ * Type-safe record mapping string values to ergonomic enum-like keys.
+ * Keys are uppercased and dots are replaced with underscores.
+ */
+type StringEnumRecord<T extends readonly string[]> = Readonly<{
+    [Value in T[number] as Uppercase<ReplaceDotsWithUnderscores<Value>>]: Value;
+}>;
+/**
+ * Creates an immutable enum-like record from a readonly string array.
+ * Example: `['foo.s', 'baz'] as const` → `{ FOO_S: 'foo.s', BAZ: 'baz' }`.
+ */
+declare function createStringEnumRecord<const T extends readonly string[]>(values: T): StringEnumRecord<T>;
+
 /**
  * Safely executes functions and handles errors without using try/catch in the calling code.
  * Example usage: `safeExecute(() => fetchData(), (error) => console.error(error))`
@@ -189,7 +207,7 @@ type MeasuredExecution<T> = {
  * Utility function to measure the execution time of an asynchronous function.
  * @returns An object containing the result of the execution and the time taken in milliseconds.
  *
- * ```ts
+ * ```typescript
  * const { result, executionTime } = await measureExecutionTime(async () => {
  *    return await fetchData();
  * });
@@ -306,7 +324,7 @@ type ZodPaginationOptions = z.infer<typeof zodPaginationSchema>;
  * 2. A `.transform()` that narrows the output type to `AtLeastOne<T>`,
  *    making it directly assignable to domain `*Select` and `*Update` types without casting.
  *
- * ```ts
+ * ```typescript
  * zQuery(zodAtLeastOne(userSelectSchema)) // result: UserSelect ✓
  * ```
  */
@@ -320,7 +338,7 @@ declare const parseQueryValue: (value: unknown) => unknown;
  * numbers or booleans. This helper converts only clear primitive values, allowing
  * regular schemas like `z.number()` and `z.boolean()` to validate query input directly.
  *
- * ```ts
+ * ```typescript
  * const schema = asQuery(z.object({
  *   page: z.number().int().positive(),
  *   isActive: z.boolean(),
@@ -338,4 +356,4 @@ declare const asQuery: <T extends z.ZodTypeAny>(schema: T) => z.ZodPreprocess<T>
  */
 declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
 
-export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AsQuery, type AtLeastOne, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type JWTServiceOptions, type JWTSignOptions, type MeasuredExecution, type Payload, type PayloadSchema, SUCCESS_STATUS_CODES, type Simplify, type SuccessStatusCode, ZodJWTService, type ZodPaginationOptions, asQuery, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, isPlainObject, log, measureExecutionTime, onHandlerError, parseQueryValue, respond, safeExecute, sqlWhere, success, zodAtLeastOne, zodPaginationSchema, zodPaginationShape };
+export { type APIContractData, type APIContractError, type APIContractResult, type APIError, type APISuccess, type AsQuery, type AtLeastOne, EXCEPTION_STATUS_CODES, type ExceptionStatusCode, type FetchResult, type JWTServiceOptions, type JWTSignOptions, type MeasuredExecution, type Payload, type PayloadSchema, type ReplaceDotsWithUnderscores, SUCCESS_STATUS_CODES, type Simplify, type StringEnumRecord, type SuccessStatusCode, ZodJWTService, type ZodPaginationOptions, asQuery, createStringEnumRecord, failure, fetchAndThrow, fetchSafely, formatTime, generateRandomString, getColoredHTTPStatus, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, honoLoggingHandler, isPlainObject, log, measureExecutionTime, onHandlerError, parseQueryValue, respond, safeExecute, sqlWhere, success, zodAtLeastOne, zodPaginationSchema, zodPaginationShape };

package/dist/index.js

@@ -142,6 +142,11 @@ async function fetchAndThrow(fetcher) {
   return response.data;
 }
 
+// src/utilities/enums.utilities.ts
+function createStringEnumRecord(values) {
+  return Object.freeze(Object.fromEntries(values.map((value) => [value.replace(/\./g, "_").toUpperCase(), value])));
+}
+
 // src/utilities/execution.utilities.ts
 async function safeExecute(fn, onError) {
   try {
@@ -260,6 +265,7 @@ export {
   SUCCESS_STATUS_CODES,
   ZodJWTService,
   asQuery,
+  createStringEnumRecord,
   failure,
   fetchAndThrow,
   fetchSafely,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.6.19",
+  "version": "0.6.21",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
   "type": "module",
   "repository": {
@@ -12,7 +12,7 @@
   },
   "scripts": {
     "build": "tsup",
-    "lint": "eslint . --ext .ts",
+    "lint": "eslint . --ext .ts --fix",
     "format": "prettier --write .",
     "typecheck": "tsc --noEmit"
   },