@kalutskii/foundation 0.7.25 → 2.0.0

package/dist/index.d.ts

@@ -32,19 +32,21 @@ type APISuccess<TData = void> = {
   status: SuccessStatusCode;
   data: TData;
 };
-type APIError = {
+type APIError<TErrorCode extends string = string> = {
   kind: 'error';
   status: ExceptionStatusCode;
-  error: string;
+  error: TErrorCode;
 };
-type APIContractResult<TData = void> = APISuccess<TData> | APIError;
+type APIContractResult<TData = void, TErrorCode extends string = string> = APISuccess<TData> | APIError<TErrorCode>;
 type APIContractData<TResult extends APIContractResult<unknown>> = TResult extends APISuccess<infer TData> ? TData : never;
 type APIContractError<TResult extends APIContractResult<unknown>> = Extract<TResult, APIError>;
-type FetchResult<TData> = {
+type APIContractErrorCode<TResult extends APIContractResult<unknown>> = APIContractError<TResult>['error'];
+type ErrorCodeOf<TErrorFactories extends Record<string, unknown>> = keyof TErrorFactories & string;
+type FetchResult<TData, TErrorCode extends string = string> = {
   error: null;
   data: TData;
 } | {
-  error: string;
+  error: TErrorCode;
   data: null;
 };
 //#endregion
@@ -186,6 +188,17 @@ declare function encodeHMACSignature(signature: Uint8Array, encoding: HMACEncodi
  */
 declare function decodeHMACSignature(signature: string, encoding: HMACEncoding): Uint8Array<ArrayBuffer>;
 //#endregion
+//#region src/http/http.errors.d.ts
+/**
+ * Represents an error envelope rejected by an API request resolver.
+ * The original status and typed code remain available for client handling.
+ */
+declare class APIRequestError<TErrorCode extends string = string> extends Error {
+  readonly code: TErrorCode;
+  readonly status: ExceptionStatusCode;
+  constructor(status: ExceptionStatusCode, code: TErrorCode);
+}
+//#endregion
 //#region src/http/http.factory.d.ts
 /**
  * Creates a successful API envelope without cloning its data.
@@ -197,22 +210,22 @@ declare function success<T = unknown>({ status, data }: {
 }): APISuccess<T>;
 /**
  * Creates a failed API envelope with one supported exception status.
- * The supplied message remains unchanged for downstream presentation.
+ * The supplied error code remains unchanged for downstream resolution.
  */
-declare function failure({ status, error }: {
+declare function failure<const TErrorCode extends string>({ status, error }: {
   status: ExceptionStatusCode;
-  error: string;
-}): APIError;
+  error: TErrorCode;
+}): APIError<TErrorCode>;
 //#endregion
 //#region src/http/http.resolvers.d.ts
 /**
  * Converts an API contract envelope into a mutually exclusive safe result.
  * Only `APIError` values are normalized; rejected fetchers still reject.
  */
-declare function fetchSafely<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<FetchResult<APIContractData<TResult>>>;
+declare function fetchSafely<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<FetchResult<APIContractData<TResult>, APIContractErrorCode<TResult>>>;
 /**
- * Returns successful API data and throws for an `APIError` envelope.
- * Rejected fetchers propagate their original error without replacement.
+ * Returns successful API data and throws `APIRequestError` for a failed envelope.
+ * Transport and programming rejections propagate without replacement.
  */
 declare function fetchAndThrow<TResult extends APIContractResult<unknown>>(fetcher: () => Promise<TResult>): Promise<APIContractData<TResult>>;
 //#endregion
@@ -1069,4 +1082,4 @@ declare function stringifyPayloadValues<TValue>(value: TValue): StringifiedPaylo
  */
 declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
 //#endregion
-export { APIContractData, APIContractError, APIContractResult, APIError, APISuccess, AtLeastOne, DEFAULT_HMAC_ALGORITHM, DEFAULT_HMAC_ENCODING, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, ExceptionStatusCode, FetchResult, FileFormat, FileFormatConfig, HMACAlgorithm, HMACEncoding, HMACInput, HMACService, HMACServiceOptions, HonoFileRespondOptions, HonoRespondOptions, JWTServiceOptions, JWTSignOptions, LogLevel, MeasuredExecution, Payload, PayloadSchema, REDACTED_LOG_VALUE, ReplaceDotsWithUnderscores, ReplaceHyphensWithUnderscores, SUCCESS_STATUS_CODES, Simplify, StringEnumRecord, StringifiedPayload, SuccessStatusCode, UploadFilesValidationOptions, UploadFilesValidationResult, UploadPreset, UploadValidationError, ZodBulkExcludeSelection, ZodBulkIncludeSelection, ZodBulkSelection, ZodJWTService, ZodPaginationOptions, ZodSearchSchemaOptions, ZodUploadFileSchemaOptions, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, decodeBase64, decodeHMACSignature, defineUploadPreset, documentUploadPreset, encodeBase64, encodeHMACSignature, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, hmacAlgorithm, hmacAlgorithmsArray, hmacAlgorithmsRecord, hmacEncoding, hmacEncodingsArray, hmacEncodingsRecord, httpStatusColors, imageTransparentUploadPreset, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, redactSensitiveJSON, redactSensitiveSearchParams, respond, safeExecute, sensitiveLogKeyParts, sqlWhere, stringifyPayloadValues, success, toHMACBytes, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };
+export { APIContractData, APIContractError, APIContractErrorCode, APIContractResult, APIError, APIRequestError, APISuccess, AtLeastOne, DEFAULT_HMAC_ALGORITHM, DEFAULT_HMAC_ENCODING, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, ErrorCodeOf, ExceptionStatusCode, FetchResult, FileFormat, FileFormatConfig, HMACAlgorithm, HMACEncoding, HMACInput, HMACService, HMACServiceOptions, HonoFileRespondOptions, HonoRespondOptions, JWTServiceOptions, JWTSignOptions, LogLevel, MeasuredExecution, Payload, PayloadSchema, REDACTED_LOG_VALUE, ReplaceDotsWithUnderscores, ReplaceHyphensWithUnderscores, SUCCESS_STATUS_CODES, Simplify, StringEnumRecord, StringifiedPayload, SuccessStatusCode, UploadFilesValidationOptions, UploadFilesValidationResult, UploadPreset, UploadValidationError, ZodBulkExcludeSelection, ZodBulkIncludeSelection, ZodBulkSelection, ZodJWTService, ZodPaginationOptions, ZodSearchSchemaOptions, ZodUploadFileSchemaOptions, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, decodeBase64, decodeHMACSignature, defineUploadPreset, documentUploadPreset, encodeBase64, encodeHMACSignature, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, hmacAlgorithm, hmacAlgorithmsArray, hmacAlgorithmsRecord, hmacEncoding, hmacEncodingsArray, hmacEncodingsRecord, httpStatusColors, imageTransparentUploadPreset, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, redactSensitiveJSON, redactSensitiveSearchParams, respond, safeExecute, sensitiveLogKeyParts, sqlWhere, stringifyPayloadValues, success, toHMACBytes, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };

package/dist/index.js

@@ -36,7 +36,7 @@ function success({ status, data }) {
 }
 /**
 * Creates a failed API envelope with one supported exception status.
-* The supplied message remains unchanged for downstream presentation.
+* The supplied error code remains unchanged for downstream resolution.
 */
 function failure({ status, error }) {
 	return {
@@ -423,6 +423,22 @@ const EXCEPTION_STATUS_CODES = [
 	500
 ];
 //#endregion
+//#region src/http/http.errors.ts
+/**
+* Represents an error envelope rejected by an API request resolver.
+* The original status and typed code remain available for client handling.
+*/
+var APIRequestError = class extends Error {
+	code;
+	status;
+	constructor(status, code) {
+		super(code);
+		this.name = "APIRequestError";
+		this.code = code;
+		this.status = status;
+	}
+};
+//#endregion
 //#region src/http/http.resolvers.ts
 /**
 * Converts an API contract envelope into a mutually exclusive safe result.
@@ -440,12 +456,12 @@ async function fetchSafely(fetcher) {
 	};
 }
 /**
-* Returns successful API data and throws for an `APIError` envelope.
-* Rejected fetchers propagate their original error without replacement.
+* Returns successful API data and throws `APIRequestError` for a failed envelope.
+* Transport and programming rejections propagate without replacement.
 */
 async function fetchAndThrow(fetcher) {
 	const response = await fetcher();
-	if (response.kind === "error") throw new Error(response.error);
+	if (response.kind === "error") throw new APIRequestError(response.status, response.error);
 	return response.data;
 }
 //#endregion
@@ -1037,4 +1053,4 @@ function stringifyPayloadValues(value) {
 	return String(value);
 }
 //#endregion
-export { DEFAULT_HMAC_ALGORITHM, DEFAULT_HMAC_ENCODING, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, HMACService, REDACTED_LOG_VALUE, SUCCESS_STATUS_CODES, ZodJWTService, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, decodeBase64, decodeHMACSignature, defineUploadPreset, documentUploadPreset, encodeBase64, encodeHMACSignature, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, hmacAlgorithm, hmacAlgorithmsArray, hmacAlgorithmsRecord, hmacEncoding, hmacEncodingsArray, hmacEncodingsRecord, httpStatusColors, imageTransparentUploadPreset, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, redactSensitiveJSON, redactSensitiveSearchParams, respond, safeExecute, sensitiveLogKeyParts, sqlWhere, stringifyPayloadValues, success, toHMACBytes, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };
+export { APIRequestError, DEFAULT_HMAC_ALGORITHM, DEFAULT_HMAC_ENCODING, DEFAULT_UPLOAD_MAX_FILE_SIZE, EXCEPTION_STATUS_CODES, HMACService, REDACTED_LOG_VALUE, SUCCESS_STATUS_CODES, ZodJWTService, asQuery, createStringEnumRecord, createUploadAccept, createZodSearchWhereSchema, decodeBase64, decodeHMACSignature, defineUploadPreset, documentUploadPreset, encodeBase64, encodeHMACSignature, failure, fetchAndThrow, fetchSafely, fileFormat, fileFormatsArray, fileFormatsConfig, fileFormatsRecord, fileRespond, formatTime, generateRandomString, getColoredHTTPStatus, getFileExtension, getFormattedDate, getFormattedTime, getUTCOffset, getZonedTime, hmacAlgorithm, hmacAlgorithmsArray, hmacAlgorithmsRecord, hmacEncoding, hmacEncodingsArray, hmacEncodingsRecord, httpStatusColors, imageTransparentUploadPreset, imageUploadPreset, isFileExtensionSupported, isFileFormatSupported, isFileMimeTypeSupported, isPlainObject, log, logLevel, logLevelColors, logLevelsArray, logLevelsRecord, loggingMiddleware, matchesMimeType, measureExecutionTime, normalizeFileExtension, onHandlerError, parseQueryValue, redactSensitiveJSON, redactSensitiveSearchParams, respond, safeExecute, sensitiveLogKeyParts, sqlWhere, stringifyPayloadValues, success, toHMACBytes, uploadValidationError, uploadValidationErrorsArray, uploadValidationErrorsRecord, validateUploadFile, validateUploadFiles, zodAtLeastOne, zodBulkSelectionSchema, zodPaginationSchema, zodPaginationShape, zodSearchQuerySchema, zodSearchSchema, zodUploadFileSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalutskii/foundation",
-  "version": "0.7.25",
+  "version": "2.0.0",
   "description": "Typescript collection of most common utilities, schemas and functions among private projects.",
   "license": "MIT",
   "repository": {