@poppinss/utils 6.5.0-2 → 6.5.0-4

package/README.md

@@ -557,6 +557,7 @@ string.bytes.format(1024 * 1024 * 1000, { thousandsSeparator: ',' }) // 1,000MB
 ```
 
 ### String builder
+
 The string builder offers a fluent API for applying a set of transforms on a string value. You can create an instance of the string builder as follows.
 
 ```ts
@@ -938,6 +939,7 @@ await Promise.all(
 ```
 
 #### importDefault
+
 A helper function that assert a lazy import function output to have a `default export`, otherwise raises an exception.
 
 We use dynamic default exports a lot in AdonisJS apps, so extracting the check to a helper function.

package/build/index.d.ts

@@ -1,19 +1,284 @@
-/// <reference types="node" resolution-mode="require"/>
-export { base64 } from './src/base64.js';
-export { compose } from './src/compose.js';
-export { importDefault } from './src/import_default.js';
-export { defineStaticProperty } from './src/define_static_property.js';
-export { Exception, createError } from './src/exception.js';
-export { flatten } from './src/flatten.js';
-export { fsImportAll } from './src/fs_import_all.js';
-export { fsReadAll } from './src/fs_read_all.js';
-export { isScriptFile } from './src/is_script_file.js';
-export { MessageBuilder } from './src/message_builder.js';
-export { naturalSort } from './src/natural_sort.js';
-export { ObjectBuilder } from './src/object_builder.js';
-export { safeEqual } from './src/safe_equal.js';
-export { slash } from './src/slash.js';
-export { RuntimeException } from './src/exceptions/runtime_exception.js';
-export { InvalidArgumentsException } from './src/exceptions/invalid_arguments_exception.js';
-export declare function getDirname(url: string | URL): string;
-export declare function getFilename(url: string | URL): string;
+import { Constructor as Constructor$1, ImportAllFilesOptions, ReadAllFilesOptions, OmitProperties } from './src/types.js';
+export { default as slash } from 'slash';
+
+/**
+ * Helper class to base64 encode/decode values with option
+ * for url encoding and decoding
+ */
+declare class Base64 {
+    /**
+     * Base64 encode Buffer or string
+     */
+    encode(arrayBuffer: ArrayBuffer | SharedArrayBuffer): string;
+    encode(data: string, encoding?: BufferEncoding): string;
+    /**
+     * Base64 decode a previously encoded string or Buffer.
+     */
+    decode(encode: string, encoding: BufferEncoding, strict: true): string;
+    decode(encode: string, encoding: undefined, strict: true): string;
+    decode(encode: string, encoding?: BufferEncoding, strict?: false): string | null;
+    decode(encode: Buffer, encoding?: BufferEncoding): string;
+    /**
+     * Base64 encode Buffer or string to be URL safe. (RFC 4648)
+     */
+    urlEncode(arrayBuffer: ArrayBuffer | SharedArrayBuffer): string;
+    urlEncode(data: string, encoding?: BufferEncoding): string;
+    /**
+     * Base64 URL decode a previously encoded string or Buffer. (RFC 4648)
+     */
+    urlDecode(encode: string, encoding: BufferEncoding, strict: true): string;
+    urlDecode(encode: string, encoding: undefined, strict: true): string;
+    urlDecode(encode: string, encoding?: BufferEncoding, strict?: false): string | null;
+    urlDecode(encode: Buffer, encoding?: BufferEncoding): string;
+}
+declare const base64: Base64;
+
+interface UnaryFunction<T, R> {
+    (source: T): R;
+}
+/**
+ * Compose a class by applying mixins to it.
+ * The code is inspired by https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/, its
+ * just that I have added the support for static types too.
+ */
+declare function compose<T extends Constructor$1, A>(superclass: T, mixin: UnaryFunction<T, A>): A;
+declare function compose<T extends Constructor$1, A, B>(superclass: T, mixin: UnaryFunction<T, A>, mixinB: UnaryFunction<A, B>): B;
+declare function compose<T extends Constructor$1, A, B, C>(superclass: T, mixin: UnaryFunction<T, A>, mixinB: UnaryFunction<A, B>, mixinC: UnaryFunction<B, C>): C;
+declare function compose<T extends Constructor$1, A, B, C, D>(superclass: T, mixin: UnaryFunction<T, A>, mixinB: UnaryFunction<A, B>, mixinC: UnaryFunction<B, C>, mixinD: UnaryFunction<C, D>): D;
+declare function compose<T extends Constructor$1, A, B, C, D, E>(superclass: T, mixin: UnaryFunction<T, A>, mixinB: UnaryFunction<A, B>, mixinC: UnaryFunction<B, C>, mixinD: UnaryFunction<C, D>, mixinE: UnaryFunction<D, E>): E;
+declare function compose<T extends Constructor$1, A, B, C, D, E, F>(superclass: T, mixin: UnaryFunction<T, A>, mixinB: UnaryFunction<A, B>, mixinC: UnaryFunction<B, C>, mixinD: UnaryFunction<C, D>, mixinF: UnaryFunction<E, F>): F;
+declare function compose<T extends Constructor$1, A, B, C, D, E, F, G>(superclass: T, mixin: UnaryFunction<T, A>, mixinB: UnaryFunction<A, B>, mixinC: UnaryFunction<B, C>, mixinD: UnaryFunction<C, D>, mixinF: UnaryFunction<E, F>, mixinG: UnaryFunction<F, G>): G;
+declare function compose<T extends Constructor$1, A, B, C, D, E, F, G, H>(superclass: T, mixin: UnaryFunction<T, A>, mixinB: UnaryFunction<A, B>, mixinC: UnaryFunction<B, C>, mixinD: UnaryFunction<C, D>, mixinF: UnaryFunction<E, F>, mixinG: UnaryFunction<F, G>, mixinH: UnaryFunction<G, H>): H;
+declare function compose<T extends Constructor$1, A, B, C, D, E, F, G, H, I>(superclass: T, mixin: UnaryFunction<T, A>, mixinB: UnaryFunction<A, B>, mixinC: UnaryFunction<B, C>, mixinD: UnaryFunction<C, D>, mixinF: UnaryFunction<E, F>, mixinG: UnaryFunction<F, G>, mixinH: UnaryFunction<G, H>, mixinI: UnaryFunction<H, I>): I;
+
+/**
+ * Dynamically import a module and ensure it has a default export
+ */
+declare function importDefault<T extends object>(importFn: () => Promise<T>, filePath?: string): Promise<T extends {
+    default: infer A;
+} ? A : never>;
+
+type Constructor = new (...args: any[]) => any;
+type AbstractConstructor = abstract new (...args: any[]) => any;
+/**
+ * Define static properties on a class with inheritance in play.
+ */
+declare function defineStaticProperty<T extends Constructor | AbstractConstructor, Prop extends keyof T>(self: T, propertyName: Prop, { initialValue, strategy, }: {
+    initialValue: T[Prop];
+    strategy: 'inherit' | 'define' | ((value: T[Prop]) => T[Prop]);
+}): void;
+
+/**
+ * Extended Error object with the option to set error `status` and `code`.
+ * At AdonisJs, we prefer exceptions with proper error codes to handle
+ * them without relying on message pattern matching.
+ *
+ * ```js
+ * new Exception('message', 500, 'E_RUNTIME_EXCEPTION')
+ * ```
+ */
+declare class Exception extends Error {
+    /**
+     * Static properties to defined on the exception once
+     * and then re-use them
+     */
+    static help?: string;
+    static code?: string;
+    static status?: number;
+    static message?: string;
+    /**
+     * Name of the class that raised the exception.
+     */
+    name: string;
+    /**
+     * Optional help description for the error. You can use it to define additional
+     * human readable information for the error.
+     */
+    help?: string;
+    /**
+     * A machine readable error code. This will allow the error handling logic
+     * to narrow down exceptions based upon the error code.
+     */
+    code?: string;
+    /**
+     * A status code for the error. Usually helpful when converting errors
+     * to HTTP responses.
+     */
+    status: number;
+    constructor(message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    });
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+}
+/**
+ * Helper to create anonymous error classes
+ */
+declare function createError<T extends any[] = never>(message: string, code: string, status?: number): typeof Exception & T extends never ? {
+    new (args?: any, options?: ErrorOptions): Exception;
+} : {
+    new (args: T, options?: ErrorOptions): Exception;
+};
+
+/**
+ * Recursively flatten an object/array.
+ */
+declare function flatten<X = Record<string, any>, Y = unknown>(input: Y, glue?: string, keepNullish?: boolean): X;
+
+/**
+ * Returns an array of file paths from the given location. You can
+ * optionally filter and sort files by passing relevant options
+ *
+ * ```ts
+ * await fsReadAll(new URL('./', import.meta.url))
+ *
+ * await fsReadAll(new URL('./', import.meta.url), {
+ *   filter: (filePath) => filePath.endsWith('.js')
+ * })
+
+ * await fsReadAll(new URL('./', import.meta.url), {
+ *   absolute: true,
+ *   unixPaths: true
+ * })
+* ```
+ */
+declare function fsImportAll(location: string | URL, options?: ImportAllFilesOptions): Promise<any>;
+
+/**
+ * Returns an array of file paths from the given location. You can
+ * optionally filter and sort files by passing relevant options
+ *
+ * ```ts
+ * await fsReadAll(new URL('./', import.meta.url))
+ *
+ * await fsReadAll(new URL('./', import.meta.url), {
+ *   filter: (filePath) => filePath.endsWith('.js')
+ * })
+
+ * await fsReadAll(new URL('./', import.meta.url), {
+ *   absolute: true,
+ *   unixPaths: true
+ * })
+* ```
+ */
+declare function fsReadAll(location: string | URL, options?: ReadAllFilesOptions): Promise<string[]>;
+
+/**
+ * Returns `true` when file ends with `.js`, `.json` or
+ * `.ts` but not `.d.ts`.
+ */
+declare function isScriptFile(filePath: string): boolean;
+
+/**
+ * Message builder exposes an API to "JSON.stringify" values by
+ * encoding purpose and expiry date inside them.
+ *
+ * The return value must be further encrypted to prevent tempering.
+ */
+declare class MessageBuilder {
+    #private;
+    /**
+     * Builds a message by encoding expiry date and purpose inside it.
+     */
+    build(message: any, expiresIn?: string | number, purpose?: string): string;
+    /**
+     * Verifies the message for expiry and purpose.
+     */
+    verify<T extends any>(message: any, purpose?: string): null | T;
+}
+
+/**
+ * Perform natural sorting with "Array.sort()" method
+ */
+declare function naturalSort(current: string, next: string): number;
+
+/**
+ * A simple class to build an object incrementally. It is helpful when you
+ * want to add properties to the object conditionally.
+ *
+ * Instead of writing
+ * ```
+ * const obj = {
+ *   ...(user.id ? { id: user.id } : {}),
+ *   ...(user.firstName && user.lastName ? { name: `${user.firstName} ${user.lastName}` } : {}),
+ * }
+ * ```
+ *
+ * You can write
+ *
+ * const obj = new ObjectBuilder()
+ *   .add('id', user.id)
+ *   .add(
+ *     'fullName',
+ *     user.firstName && user.lastName ? `${user.firstName} ${user.lastName}` : undefined
+ *   )
+ *   .toObject()
+ */
+declare class ObjectBuilder<ReturnType extends Record<string, any>, IgnoreNull extends boolean = false> {
+    #private;
+    values: ReturnType;
+    constructor(initialValue: ReturnType, ignoreNull?: IgnoreNull);
+    /**
+     * Add a key-value pair to the object
+     *
+     * - Undefined values are ignored
+     * - Null values are ignored, when `ignoreNull` is set to true
+     */
+    add<Prop extends string>(key: Prop, value: undefined): this;
+    add<Prop extends string, Value>(key: Prop, value: Value): ObjectBuilder<ReturnType & {
+        [P in Prop]: Value;
+    }, IgnoreNull>;
+    /**
+     * Remove key from the object
+     */
+    remove<K extends keyof ReturnType>(key: K): this;
+    /**
+     * Find if a value exists
+     */
+    has<K extends keyof ReturnType>(key: K): boolean;
+    /**
+     * Get the existing value for a given key
+     */
+    get<K extends keyof ReturnType>(key: K): ReturnType[K];
+    /**
+     * Get the underlying constructed object
+     */
+    toObject(): IgnoreNull extends true ? {
+        [K in keyof OmitProperties<ReturnType, null>]: ReturnType[K];
+    } : {
+        [K in keyof ReturnType]: ReturnType[K];
+    };
+}
+
+type BufferSafeValue = ArrayBuffer | SharedArrayBuffer | number[] | string | {
+    valueOf(): string | object;
+} | {
+    [Symbol.toPrimitive](hint: 'string'): string;
+};
+/**
+ * Compare two values to see if they are equal. The comparison is done in
+ * a way to avoid timing-attacks.
+ */
+declare function safeEqual<T extends BufferSafeValue, U extends BufferSafeValue>(trustedValue: T, userInput: U): boolean;
+
+declare class RuntimeException extends Exception {
+    static code: string;
+    static status: number;
+}
+
+declare class InvalidArgumentsException extends Exception {
+    static code: string;
+    static status: number;
+}
+
+/**
+ * Get dirname for a given file path URL
+ */
+declare function getDirname(url: string | URL): string;
+/**
+ * Get filename for a given file path URL
+ */
+declare function getFilename(url: string | URL): string;
+
+export { Exception, InvalidArgumentsException, MessageBuilder, ObjectBuilder, RuntimeException, base64, compose, createError, defineStaticProperty, flatten, fsImportAll, fsReadAll, getDirname, getFilename, importDefault, isScriptFile, naturalSort, safeEqual };