@lokalise/node-core 12.5.1 → 13.0.0

package/dist/index.d.ts

@@ -1,29 +1,404 @@
-export type { ErrorDetails } from './src/errors/types';
-export { PublicNonRecoverableError, isPublicNonRecoverableError, type PublicNonRecoverableErrorParams, } from './src/errors/PublicNonRecoverableError';
-export { InternalError, isInternalError, type InternalErrorParams, } from './src/errors/InternalError';
-export { isEntityGoneError } from './src/errors/errorTypeGuards';
-export { ConfigScope } from './src/config/ConfigScope';
-export { ensureClosingSlashTransformer } from './src/config/configTransformers';
-export { createRangeValidator } from './src/config/configValidators';
-export { type EnvValueValidator, type EnvValueTransformer, type AppConfig, type RedisConfig, } from './src/config/configTypes';
-export { type Either, type DefiniteEither, success, failure, isSuccess, isFailure, } from './src/errors/either';
-export { EncryptionUtility } from './src/utils/encryptionUtility';
-export { chunk, callChunked, removeFalsy, removeNullish, removeDuplicates, } from './src/utils/arrayUtils';
-export { groupBy, groupByPath, groupByUnique, pick, pickWithoutUndefined, copyWithoutUndefined, copyWithoutEmpty, isEmptyObject, convertDateFieldsToIsoString, deepClone, } from './src/utils/objectUtils';
-export { isError, isStandardizedError, isObject, hasMessage, } from './src/utils/typeUtils';
-export { type StandardizedError } from './src/utils/typeUtils';
-export { generateHash, HashAlgorithm, HashEncoding } from './src/utils/hashUtils';
-export { resolveLoggerConfiguration, resolveMonorepoLoggerConfiguration, resolveLogger, resolveMonorepoLogger, } from './src/logging/loggerConfigResolver';
-export type { AppLoggerConfig, MonorepoAppLoggerConfig } from './src/logging/loggerConfigResolver';
-export type { CommonLogger } from './src/logging/commonLogger';
-export { type ErrorReport, type ErrorReporter, type ErrorResolver, } from './src/errors/errorReporterTypes';
-export { executeAsyncAndHandleGlobalErrors, executeAndHandleGlobalErrors, executeSettleAllAndHandleGlobalErrors, globalLogger, resolveGlobalErrorLogObject, } from './src/errors/globalErrorHandler';
-export { type MayOmit } from './src/common/may-omit';
-export { type FreeformRecord } from './src/common/commonTypes';
-export { type ValidationError, type CommonErrorParams, type OptionalMessageErrorParams, RequestValidationError, AccessDeniedError, EntityNotFoundError, EntityGoneError, AuthFailedError, } from './src/errors/publicErrors';
-export { waitAndRetry } from './src/utils/waitUtils';
-export type { TransactionObservabilityManager } from './src/observability/observabilityTypes';
-export { MultiTransactionObservabilityManager } from './src/observability/MultiTransactionObservabilityManager';
-export { generateChecksumForReadable, generateChecksumForObject, generateChecksumForBufferOrString, } from './src/utils/checksumUtils';
-export { FsReadableProvider } from './src/utils/streamUtils';
-export type { PersistToFsOptions, ReadableProvider, FsReadableProviderOptions, } from './src/utils/streamUtils';
+import { ZodSchema } from 'zod';
+import { redactOptions, Logger, LoggerOptions, BaseLogger, Bindings, ChildLoggerOptions, SerializedError } from 'pino';
+import { BinaryLike } from 'node:crypto';
+import { Readable } from 'node:stream';
+
+type ErrorDetails = Record<string, unknown>;
+
+type PublicNonRecoverableErrorParams<T = ErrorDetails> = {
+    message: string;
+    errorCode: string;
+    details?: T;
+    httpStatusCode?: number;
+    cause?: unknown;
+};
+declare const publicNonRecoverableErrorSymbol: unique symbol;
+/**
+ * This error is returned to the consumer of API
+ */
+declare class PublicNonRecoverableError<T = ErrorDetails> extends Error {
+    readonly [publicNonRecoverableErrorSymbol] = true;
+    readonly details?: T;
+    readonly errorCode: string;
+    readonly httpStatusCode: number;
+    constructor(params: PublicNonRecoverableErrorParams<T>);
+}
+declare function isPublicNonRecoverableError(error: unknown): error is PublicNonRecoverableError;
+
+type InternalErrorParams<T = ErrorDetails> = {
+    message: string;
+    errorCode: string;
+    details?: T;
+    cause?: unknown;
+};
+declare const internalErrorSymbol: unique symbol;
+declare class InternalError<T = ErrorDetails> extends Error {
+    readonly [internalErrorSymbol] = true;
+    readonly details?: T;
+    readonly errorCode: string;
+    constructor(params: InternalErrorParams<T>);
+}
+declare function isInternalError(error: unknown): error is InternalError;
+
+type FreeformRecord = Record<string, any>;
+
+type CommonErrorParams = {
+    message: string;
+    details?: FreeformRecord;
+    cause?: Error;
+};
+type OptionalMessageErrorParams = Partial<CommonErrorParams>;
+type ValidationError = {
+    message: string;
+    path: string[];
+};
+declare class RequestValidationError extends PublicNonRecoverableError {
+    constructor(errors: ValidationError[]);
+}
+declare class AccessDeniedError extends PublicNonRecoverableError {
+    constructor(params: CommonErrorParams);
+}
+declare class EntityNotFoundError extends PublicNonRecoverableError {
+    constructor(params: CommonErrorParams);
+}
+declare class EntityGoneError extends PublicNonRecoverableError {
+    constructor(params: CommonErrorParams);
+}
+declare class AuthFailedError extends PublicNonRecoverableError {
+    constructor(params?: OptionalMessageErrorParams);
+}
+
+declare function isEntityGoneError(entity: unknown): entity is EntityGoneError;
+
+type EnvValueValidator<InputType> = (value: InputType) => boolean;
+type EnvValueTransformer<InputType, OutputType> = (value: InputType) => OutputType;
+type RedisConfig = {
+    host: string;
+    /**
+     * An integer from 0 to 15, inclusive
+     */
+    db?: number;
+    keyPrefix?: string;
+    port: number;
+    username?: string;
+    password?: string;
+    commandTimeout?: number;
+    connectTimeout?: number;
+    /**
+     * Set this option explicitly to null for infinite retries
+     * By default (for undefined) there are 20 retries, see: https://redis.github.io/ioredis/interfaces/CommonRedisOptions.html#maxRetriesPerRequest
+     */
+    maxRetriesPerRequest?: number | null;
+    enableReadyCheck?: boolean;
+    lazyConnect?: boolean;
+    useTls: boolean;
+};
+type AppConfig = {
+    port: number;
+    bindAddress: string;
+    logLevel: string;
+    nodeEnv: 'production' | 'development' | 'test';
+    appEnv: 'production' | 'development' | 'staging';
+};
+
+type EnvType = {
+    [key: string]: string | undefined;
+};
+declare class ConfigScope {
+    private env;
+    constructor(envOverride?: EnvType);
+    updateEnv(): void;
+    getMandatoryInteger(param: string): number;
+    getMandatory(param: string): string;
+    getMandatoryOneOf<const T>(param: string, supportedValues: T[]): T;
+    getMandatoryValidatedInteger(param: string, validator: EnvValueValidator<number>): number;
+    getOptionalNullable<T extends string | null | undefined>(param: string, defaultValue: T): T | string;
+    getOptional(param: string, defaultValue: string): string;
+    getOptionalInteger(param: string, defaultValue: number): number;
+    getOptionalNullableInteger<T extends number | null | undefined>(param: string, defaultValue: T): T | number;
+    getOptionalOneOf<const T extends string>(param: string, defaultValue: T, supportedValues: T[]): T;
+    getOptionalValidated(param: string, defaultValue: string, validator: EnvValueValidator<string>): string;
+    getOptionalValidatedInteger(param: string, defaultValue: number, validator: EnvValueValidator<number>): number;
+    getOptionalTransformed(param: string, defaultValue: string, transformer: (value: string) => string): string;
+    getOptionalNullableTransformed<T extends string | undefined>(param: string, defaultValue: T, transformer: (value: T | string) => T | string): T | string;
+    getMandatoryTransformed(param: string, transformer: (value: string) => string): string;
+    getOptionalBoolean(param: string, defaultValue: boolean): boolean;
+    getMandatoryJsonObject<T extends object>(param: string, schema: ZodSchema<T>): T;
+    getOptionalNullableJsonObject<T extends object, Z extends T | null | undefined>(param: string, schema: ZodSchema<T>, defaultValue: Z): Z;
+    getOptionalJsonObject<T extends object>(param: string, schema: ZodSchema<T>, defaultValue: T): T;
+    isProduction(): boolean;
+    isDevelopment(): boolean;
+    isTest(): boolean;
+    private validateSchema;
+}
+
+declare const ensureClosingSlashTransformer: EnvValueTransformer<string | undefined | null, string>;
+
+declare const createRangeValidator: (greaterOrEqualThan: number, lessOrEqualThan: number) => EnvValueValidator<number>;
+
+type Left<T> = {
+    error: T;
+    result?: never;
+};
+type Right<U> = {
+    error?: never;
+    result: U;
+};
+/**
+ * Either is a functional programming type which is used to communicate errors happening in potentially recoverable scenarios.
+ * It can return either an error (Left side) or a resolved result (Right side), but not both.
+ * It is up to caller of the function to handle received error or throw (Public)NonRecoverableError if it cannot.
+ *
+ * @see {@link https://antman-does-software.com/stop-catching-errors-in-typescript-use-the-either-type-to-make-your-code-predictable Further reading on motivation for Either type}
+ */
+type Either<T, U> = NonNullable<Left<T> | Right<U>>;
+/***
+ * Variation of Either, which may or may not have Error set, but always has Result
+ */
+type DefiniteEither<T, U> = {
+    error?: T;
+    result: U;
+};
+declare const isFailure: <T, U>(e: Either<T, U>) => e is Left<T>;
+declare const isSuccess: <T, U>(e: Either<T, U>) => e is Right<U>;
+declare const failure: <T>(error: T) => Left<T>;
+declare const success: <U>(result: U) => Right<U>;
+
+type Options = {
+    saltLength?: number;
+    pbkdf2Iterations?: number;
+    encoding?: NodeJS.BufferEncoding;
+};
+/**
+ * Type-scripted version of https://github.com/MauriceButler/cryptr
+ */
+declare class EncryptionUtility {
+    private readonly secret;
+    private readonly saltLength;
+    private readonly encryptedPosition;
+    private readonly tagPosition;
+    private readonly pbkdf2Iterations;
+    private readonly encoding;
+    constructor(secret: string, options?: Options);
+    private getKey;
+    encrypt(value: string): string;
+    decrypt(value: string): string;
+}
+
+declare function chunk<T>(array: T[], chunkSize: number): T[][];
+declare function callChunked<Item>(chunkSize: number, array: readonly Item[], processFn: (arrayChunk: Item[]) => Promise<unknown>): Promise<void>;
+/**
+ * Return a copy of the given array without null or undefined values
+ */
+declare function removeNullish<const T>(array: readonly (T | null | undefined)[]): T[];
+/**
+ * Return a copy of the given array without falsy values (eg: false, 0, '', null, undefined)
+ */
+declare function removeFalsy<const T>(array: readonly (T | null | undefined | 0 | '' | false)[]): T[];
+/**
+ * Return a copy of the given array without duplicates.
+ */
+declare function removeDuplicates<const T>(array: readonly T[]): T[];
+
+type RecordKeyType = string | number | symbol;
+declare function copyWithoutUndefined<T extends Record<RecordKeyType, unknown>, TargetRecordType = Pick<T, {
+    [Prop in keyof T]: T[Prop] extends null | undefined ? never : Prop;
+}[keyof T]>>(originalValue: T): TargetRecordType;
+declare function copyWithoutEmpty<T extends Record<RecordKeyType, unknown>, TargetRecordType = Pick<T, {
+    [Prop in keyof T]: T[Prop] extends null | undefined | '' ? never : Prop;
+}[keyof T]>>(originalValue: T): TargetRecordType;
+declare function pick<T, K extends string | number | symbol>(source: T, propNames: readonly K[]): Pick<T, Exclude<keyof T, Exclude<keyof T, K>>>;
+declare function pickWithoutUndefined<T, K extends string | number | symbol>(source: T, propNames: readonly K[]): Pick<T, Exclude<keyof T, Exclude<keyof T, K>>>;
+declare function isEmptyObject(params: Record<string, unknown>): boolean;
+type KeysMatching<T, V> = {
+    [K in keyof T]: T[K] extends V ? K : never;
+}[keyof T];
+/**
+ * @param array The array of objects to be grouped.
+ * @param selector The key used for grouping the objects.
+ * @returns An object where the keys are unique values from the given selector and the values are the corresponding objects from the array.
+ */
+declare function groupBy<T extends object, K extends KeysMatching<T, RecordKeyType | null | undefined>>(array: T[], selector: K): Record<RecordKeyType, T[]>;
+/**
+ * @param array The array of objects to be grouped.
+ * @param selector The key used for grouping the objects. Support nested keys.
+ * @returns An object where the keys are unique values from the given selector and the values are the corresponding objects from the array.
+ */
+declare function groupByPath<T extends object>(array: T[], selector: string): Record<string, T[]>;
+/**
+ * @param array The array of objects to be grouped.
+ * @param selector The key used for grouping the objects.
+ * @returns An object where the keys are unique values from the given selector and the value is the
+ *  corresponding object from the array.
+ * @throws InternalError If a duplicated value is found for the given selector.
+ */
+declare function groupByUnique<T extends object, K extends KeysMatching<T, RecordKeyType | null | undefined>>(array: T[], selector: K): Record<RecordKeyType, T>;
+type DatesAsString<T> = T extends Date ? string : ExactlyLikeWithDateAsString<T>;
+type ExactlyLikeWithDateAsString<T> = T extends object ? {
+    [K in keyof T]: DatesAsString<T[K]>;
+} : T;
+declare function convertDateFieldsToIsoString<Input extends object>(object: Input): ExactlyLikeWithDateAsString<Input>;
+declare function convertDateFieldsToIsoString<Input extends object>(object: Input[]): ExactlyLikeWithDateAsString<Input>[];
+/**
+ * Return a deep clone copy of an object.
+ *
+ * Please Note: This uses structuredClone, which has the limitations of these restricted Types: functions,
+ * Error objects, WeakMap, WeakSet, DOM nodes, and certain other browser-specific objects like Window.
+ */
+declare function deepClone<T extends object | undefined | null>(object: T): T;
+
+type StandardizedError = {
+    code: string;
+    message: string;
+};
+declare function hasMessage(maybe: unknown): maybe is {
+    message: string;
+};
+declare function isObject(maybeObject: unknown): maybeObject is Record<PropertyKey, unknown>;
+declare function isStandardizedError(error: unknown): error is StandardizedError;
+declare function isError(maybeError: unknown): maybeError is Error;
+
+declare enum HashEncoding {
+    HEX = "hex",
+    BASE64 = "base64"
+}
+declare enum HashAlgorithm {
+    SHA256 = "sha256",
+    SHA512 = "sha512"
+}
+declare function generateHash(algorithm: HashAlgorithm, data: string, encoding?: HashEncoding): string;
+
+type AppLoggerConfig = {
+    logLevel: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent';
+    nodeEnv: 'production' | 'development' | 'test';
+    base?: Record<string, unknown>;
+    redact?: redactOptions;
+};
+type MonorepoAppLoggerConfig = AppLoggerConfig & {
+    targetFile?: string;
+    append?: boolean;
+};
+declare function resolveMonorepoLogger(appConfig: MonorepoAppLoggerConfig): Logger;
+declare function resolveMonorepoLoggerConfiguration(appConfig: MonorepoAppLoggerConfig): LoggerOptions | Logger;
+declare function resolveLogger(appConfig: AppLoggerConfig): Logger;
+declare function resolveLoggerConfiguration(appConfig: AppLoggerConfig): LoggerOptions | Logger;
+
+type CommonLogger = BaseLogger & {
+    /**
+     * Creates a child logger, setting all key-value pairs in `bindings` as properties in the log lines. All serializers will be applied to the given pair.
+     * Child loggers use the same output stream as the parent and inherit the current log level of the parent at the time they are spawned.
+     * If a `level` property is present in the object passed to `child` it will override the child logger level.
+     *
+     * @param bindings: an object of key-value pairs to include in log lines as properties.
+     * @param options: an options object that will override child logger inherited options.
+     * @returns a child logger instance.
+     */
+    child(bindings: Bindings, options?: ChildLoggerOptions): CommonLogger;
+    /**
+     * A utility method for determining if a given log level will write to the destination.
+     */
+    isLevelEnabled(level: string): boolean;
+};
+
+/**
+ * Generic interface for resolving specific kind of errors based on something that was thrown during execution
+ */
+type ErrorResolver = {
+    processError: (thrownError: unknown) => InternalError;
+};
+interface ErrorReport {
+    error: Error;
+    context?: Record<string, unknown>;
+}
+type ErrorReporter = {
+    report: (errorReport: ErrorReport) => void;
+};
+
+type LogObject = {
+    message: string;
+    'x-request-id'?: string;
+    error?: SerializedError;
+};
+declare const globalLogger: CommonLogger;
+declare function resolveGlobalErrorLogObject(err: unknown, correlationId?: string): LogObject;
+declare function executeAndHandleGlobalErrors<T>(operation: () => T): T;
+declare function executeAsyncAndHandleGlobalErrors<T>(operation: () => Promise<T>, stopOnError?: boolean): Promise<T | undefined>;
+declare function executeSettleAllAndHandleGlobalErrors(promises: Promise<unknown>[], stopOnError?: boolean): Promise<PromiseSettledResult<unknown>[]>;
+
+type MayOmit<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+
+declare const waitAndRetry: <T>(predicateFn: () => T, sleepTime?: number, maxRetryCount?: number) => Promise<T>;
+
+type TransactionObservabilityManager = {
+    /**
+     * Creates and starts a background transaction to record work done
+     *
+     * @param transactionName - used for grouping similar transactions together
+     * @param uniqueTransactionKey - used for identifying specific ongoing transaction. Must be reasonably unique to reduce possibility of collisions
+     */
+    start: (transactionName: string, uniqueTransactionKey: string) => unknown;
+    /**
+     * Creates and starts a background transaction to record work done, and relates it to a specified group
+     *
+     * @param transactionName - used for grouping similar transactions together
+     * @param uniqueTransactionKey - used for identifying specific ongoing transaction. Must be reasonably unique to reduce possibility of collisions   *
+     * @param transactionGroup - group is used for grouping related transactions with different names
+     */
+    startWithGroup: (transactionName: string, uniqueTransactionKey: string, transactionGroup: string) => void;
+    /**
+     * Ends the transaction
+     * @param uniqueTransactionKey - used for identifying specific ongoing transaction. Must be reasonably unique to reduce possibility of collisions
+     * @param wasSuccessful - indicates if the transaction was successful or not
+     */
+    stop: (uniqueTransactionKey: string, wasSuccessful?: boolean) => unknown;
+};
+
+/**
+ * Groups different TransactionObservabilityManager instances into one
+ * to facilitate tracking transactions across multiple observability tools.
+ */
+declare class MultiTransactionObservabilityManager implements TransactionObservabilityManager {
+    private readonly managers;
+    constructor(managers: TransactionObservabilityManager[]);
+    start(transactionName: string, uniqueTransactionKey: string): void;
+    startWithGroup(transactionName: string, uniqueTransactionKey: string, transactionGroup: string): void;
+    stop(uniqueTransactionKey: string, wasSuccessful?: boolean): void;
+}
+
+declare function generateChecksumForBufferOrString(data: BinaryLike): string;
+declare function generateChecksumForObject(object: object): string;
+declare function generateChecksumForReadable(readable: Readable): Promise<string>;
+
+type ReadableProvider = {
+    /**
+     * Guarantees to provide a new stream every time this is called, before `destroy` is invoked.
+     */
+    createStream(): Promise<Readable>;
+    /**
+     * Returns size of the persisted content
+     */
+    getContentLength(): Promise<number>;
+    /**
+     * Remove the persisted value. No new streams can be created after this is called
+     */
+    destroy(): Promise<void>;
+};
+type PersistToFsOptions = {
+    targetFile: string;
+    sourceReadable: Readable;
+};
+type FsReadableProviderOptions = {
+    storageFile: string;
+};
+declare class FsReadableProvider implements ReadableProvider {
+    readonly storageFile: string;
+    constructor(options: FsReadableProviderOptions);
+    fileExists(): Promise<boolean>;
+    getContentLength(): Promise<number>;
+    createStream(): Promise<Readable>;
+    destroy(): Promise<void>;
+    protected persist(sourceReadable: Readable): Promise<void>;
+    static persistReadableToFs(options: PersistToFsOptions): Promise<FsReadableProvider>;
+}
+
+export { AccessDeniedError, type AppConfig, type AppLoggerConfig, AuthFailedError, type CommonErrorParams, type CommonLogger, ConfigScope, type DefiniteEither, type Either, EncryptionUtility, EntityGoneError, EntityNotFoundError, type EnvValueTransformer, type EnvValueValidator, type ErrorDetails, type ErrorReport, type ErrorReporter, type ErrorResolver, type FreeformRecord, FsReadableProvider, type FsReadableProviderOptions, HashAlgorithm, HashEncoding, InternalError, type InternalErrorParams, type MayOmit, type MonorepoAppLoggerConfig, MultiTransactionObservabilityManager, type OptionalMessageErrorParams, type PersistToFsOptions, PublicNonRecoverableError, type PublicNonRecoverableErrorParams, type ReadableProvider, type RedisConfig, RequestValidationError, type StandardizedError, type TransactionObservabilityManager, type ValidationError, callChunked, chunk, convertDateFieldsToIsoString, copyWithoutEmpty, copyWithoutUndefined, createRangeValidator, deepClone, ensureClosingSlashTransformer, executeAndHandleGlobalErrors, executeAsyncAndHandleGlobalErrors, executeSettleAllAndHandleGlobalErrors, failure, generateChecksumForBufferOrString, generateChecksumForObject, generateChecksumForReadable, generateHash, globalLogger, groupBy, groupByPath, groupByUnique, hasMessage, isEmptyObject, isEntityGoneError, isError, isFailure, isInternalError, isObject, isPublicNonRecoverableError, isStandardizedError, isSuccess, pick, pickWithoutUndefined, removeDuplicates, removeFalsy, removeNullish, resolveGlobalErrorLogObject, resolveLogger, resolveLoggerConfiguration, resolveMonorepoLogger, resolveMonorepoLoggerConfiguration, success, waitAndRetry };