@adonisjs/core 6.19.0 → 7.0.0-next.1

package/build/src/helpers/assert.js

@@ -6,4 +6,50 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-export { assertExists, assertNotNull, assertIsDefined, assertUnreachable, } from '@poppinss/utils/assert';
+/**
+ * Assertion utilities for type-safe programming in AdonisJS. These functions
+ * provide runtime type assertions that help with TypeScript type narrowing
+ * and catching potential null/undefined issues early.
+ *
+ * @example
+ * // Type-safe null checking
+ * import { assertExists } from '@adonisjs/core/helpers'
+ *
+ * function processUser(user: User | null) {
+ *   assertExists(user) // TypeScript now knows user is not null
+ *   console.log(user.name) // Safe to access properties
+ * }
+ *
+ * @example
+ * // Exhaustiveness checking in switch statements
+ * import { assertUnreachable } from '@adonisjs/core/helpers'
+ *
+ * function handleStatus(status: 'pending' | 'completed') {
+ *   switch (status) {
+ *     case 'pending': return 'Processing...'
+ *     case 'completed': return 'Done!'
+ *     default: return assertUnreachable(status)
+ *   }
+ * }
+ */
+export { 
+/**
+ * Assert that a value exists (is not null or undefined).
+ * Throws an error if the value is null or undefined.
+ */
+assertExists, 
+/**
+ * Assert that a value is not null.
+ * Throws an error if the value is null.
+ */
+assertNotNull, 
+/**
+ * Assert that a value is defined (is not undefined).
+ * Throws an error if the value is undefined.
+ */
+assertIsDefined, 
+/**
+ * Assert that code should never reach this point.
+ * Useful for exhaustiveness checking in switch statements.
+ */
+assertUnreachable, } from '@poppinss/utils/assert';

package/build/src/helpers/is.d.ts

@@ -1,2 +1,23 @@
 import is from '@sindresorhus/is';
+/**
+ * Type checking utilities re-exported from @sindresorhus/is. Provides
+ * a comprehensive set of type-checking functions with TypeScript type guards.
+ *
+ * @example
+ * // Basic type checking
+ * import { is } from '@adonisjs/core/helpers'
+ *
+ * if (is.string(value)) {
+ *   // TypeScript knows value is string
+ *   console.log(value.toUpperCase())
+ * }
+ *
+ * @example
+ * // Complex type checking
+ * import { is } from '@adonisjs/core/helpers'
+ *
+ * is.array(value) && is.nonEmptyArray(value)
+ * is.plainObject(obj) && is.hasProperty(obj, 'name')
+ * is.number(num) && is.integer(num) && is.positive(num)
+ */
 export default is;

package/build/src/helpers/is.js

@@ -7,4 +7,25 @@
  * file that was distributed with this source code.
  */
 import is from '@sindresorhus/is';
+/**
+ * Type checking utilities re-exported from @sindresorhus/is. Provides
+ * a comprehensive set of type-checking functions with TypeScript type guards.
+ *
+ * @example
+ * // Basic type checking
+ * import { is } from '@adonisjs/core/helpers'
+ *
+ * if (is.string(value)) {
+ *   // TypeScript knows value is string
+ *   console.log(value.toUpperCase())
+ * }
+ *
+ * @example
+ * // Complex type checking
+ * import { is } from '@adonisjs/core/helpers'
+ *
+ * is.array(value) && is.nonEmptyArray(value)
+ * is.plainObject(obj) && is.hasProperty(obj, 'name')
+ * is.number(num) && is.integer(num) && is.positive(num)
+ */
 export default is;

package/build/src/helpers/main.d.ts

@@ -1,5 +1,48 @@
-export { parseImports } from 'parse-imports';
-export { createId as cuid, isCuid } from '@paralleldrive/cuid2';
-export { slash, base64, compose, Secret, joinToURL, fsReadAll, safeEqual, getDirname, getFilename, fsImportAll, MessageBuilder, } from '@poppinss/utils';
-export { VerificationToken } from './verification_token.js';
-export { parseBindingReference } from './parse_binding_reference.js';
+/**
+ * Core helper utilities for AdonisJS applications. This module provides
+ * a collection of commonly used utilities including file system operations,
+ * cryptographic functions, composition utilities, and HTTP server helpers.
+ *
+ * @example
+ * // File system utilities
+ * import { fsReadAll, fsImportAll } from '@adonisjs/core/helpers'
+ *
+ * const files = await fsReadAll(url('app/controllers'))
+ * const modules = await fsImportAll(url('app/events'))
+ *
+ * @example
+ * // Cryptographic utilities
+ * import { base64, safeEqual, Secret } from '@adonisjs/core/helpers'
+ *
+ * const encoded = base64.encode('sensitive data')
+ * const isEqual = safeEqual(hash1, hash2)
+ * const secret = new Secret('my-secret-key')
+ *
+ * @example
+ * // HTTP server helpers
+ * import { middlewareInfo, routeInfo } from '@adonisjs/core/helpers'
+ *
+ * const middleware = middlewareInfo('cors', () => {})
+ * const route = routeInfo('users.show', '/users/:id')
+ */
+/**
+ * File system utilities for reading and importing files recursively.
+ */
+export { fsReadAll, fsImportAll } from '@poppinss/utils/fs';
+/**
+ * Base64 encoding and decoding utilities.
+ */
+export { default as base64 } from '@poppinss/utils/base64';
+/**
+ * Core utilities including function composition, secret management,
+ * safe equality comparison, and message building.
+ */
+export { compose, Secret, safeEqual, MessageBuilder } from '@poppinss/utils';
+/**
+ * Verification token utility for creating secure tokens.
+ */
+export { VerificationToken } from './verification_token.ts';
+/**
+ * HTTP server helper functions for middleware and route information.
+ */
+export { middlewareInfo, routeInfo } from '@adonisjs/http-server/helpers';

package/build/src/helpers/main.js

@@ -6,8 +6,51 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-export { parseImports } from 'parse-imports';
-export { createId as cuid, isCuid } from '@paralleldrive/cuid2';
-export { slash, base64, compose, Secret, joinToURL, fsReadAll, safeEqual, getDirname, getFilename, fsImportAll, MessageBuilder, } from '@poppinss/utils';
-export { VerificationToken } from './verification_token.js';
-export { parseBindingReference } from './parse_binding_reference.js';
+/**
+ * Core helper utilities for AdonisJS applications. This module provides
+ * a collection of commonly used utilities including file system operations,
+ * cryptographic functions, composition utilities, and HTTP server helpers.
+ *
+ * @example
+ * // File system utilities
+ * import { fsReadAll, fsImportAll } from '@adonisjs/core/helpers'
+ *
+ * const files = await fsReadAll(url('app/controllers'))
+ * const modules = await fsImportAll(url('app/events'))
+ *
+ * @example
+ * // Cryptographic utilities
+ * import { base64, safeEqual, Secret } from '@adonisjs/core/helpers'
+ *
+ * const encoded = base64.encode('sensitive data')
+ * const isEqual = safeEqual(hash1, hash2)
+ * const secret = new Secret('my-secret-key')
+ *
+ * @example
+ * // HTTP server helpers
+ * import { middlewareInfo, routeInfo } from '@adonisjs/core/helpers'
+ *
+ * const middleware = middlewareInfo('cors', () => {})
+ * const route = routeInfo('users.show', '/users/:id')
+ */
+/**
+ * File system utilities for reading and importing files recursively.
+ */
+export { fsReadAll, fsImportAll } from '@poppinss/utils/fs';
+/**
+ * Base64 encoding and decoding utilities.
+ */
+export { default as base64 } from '@poppinss/utils/base64';
+/**
+ * Core utilities including function composition, secret management,
+ * safe equality comparison, and message building.
+ */
+export { compose, Secret, safeEqual, MessageBuilder } from '@poppinss/utils';
+/**
+ * Verification token utility for creating secure tokens.
+ */
+export { VerificationToken } from "./verification_token.js";
+/**
+ * HTTP server helper functions for middleware and route information.
+ */
+export { middlewareInfo, routeInfo } from '@adonisjs/http-server/helpers';

package/build/src/helpers/string.d.ts

@@ -1,42 +1,122 @@
-import { EncodeOptions } from 'he';
 import string from '@poppinss/utils/string';
+import { type EncodeOptions } from 'he';
 import StringBuilder from '@poppinss/utils/string_builder';
 /**
- * Collection of string helpers to transform a string value.
+ * Collection of string helpers to transform a string value. This object extends
+ * the base string utilities from @poppinss/utils with additional AdonisJS-specific
+ * string manipulation methods.
+ *
+ * @example
+ * // Basic string transformations
+ * stringHelpers.camelCase('hello_world') // 'helloWorld'
+ * stringHelpers.snakeCase('HelloWorld')   // 'hello_world'
+ * stringHelpers.pascalCase('hello world') // 'HelloWorld'
+ *
+ * @example
+ * // HTML escaping and encoding
+ * stringHelpers.escapeHTML('<script>alert("xss")</script>')
+ * stringHelpers.encodeSymbols('© 2023 AdonisJS')
  */
 declare const stringHelpers: typeof string & {
     /**
-     * Creates an instance of the string builder
+     * Creates an instance of the StringBuilder for efficient string concatenation.
+     *
+     * @param value - Initial string value or existing StringBuilder instance
+     *
+     * @example
+     * const builder = stringHelpers.create('Hello')
+     * builder.append(' ').append('World')
+     * console.log(builder.toString()) // 'Hello World'
      */
     create(value: string | StringBuilder): StringBuilder;
+    /**
+     * Convert a number to its ordinal form (1st, 2nd, 3rd, etc.).
+     * Alias for the `ordinal` method from @poppinss/utils.
+     *
+     * @example
+     * stringHelpers.ordinalize(1)  // '1st'
+     * stringHelpers.ordinalize(22) // '22nd'
+     */
     ordinalize: (typeof string)['ordinal'];
     /**
-     * Convert a string to a sentence
+     * Convert a string to a readable sentence format.
+     * Alias for the `sentence` method from @poppinss/utils.
+     *
+     * @example
+     * stringHelpers.toSentence('hello_world') // 'Hello world'
+     * stringHelpers.toSentence('firstName')   // 'First name'
      */
     toSentence: (typeof string)['sentence'];
     /**
-     * Generate a random string value of a given length
+     * Generate a cryptographically secure random string of specified length.
+     * Alias for the `random` method from @poppinss/utils.
+     *
+     * @example
+     * stringHelpers.generateRandom(16) // 'a1b2c3d4e5f6g7h8'
+     * stringHelpers.generateRandom(32) // Long random string
      */
     generateRandom: (typeof string)['random'];
     /**
-     * Pretty print hrtime diff
+     * Convert high-resolution time difference to a human-readable format.
+     *
+     * @param time - High-resolution time tuple from process.hrtime()
+     * @param options - Formatting options
+     * @param options.verbose - Use verbose format (e.g., '1 second' vs '1s')
+     * @param options.precise - Show precise decimal places
+     *
+     * @example
+     * const start = process.hrtime()
+     * // ... some operation
+     * const diff = process.hrtime(start)
+     * stringHelpers.prettyHrTime(diff) // '2.5ms'
+     * stringHelpers.prettyHrTime(diff, { verbose: true }) // '2 milliseconds'
      */
     prettyHrTime(time: [number, number], options?: {
         verbose?: boolean | undefined;
         precise?: boolean | undefined;
     }): string;
     /**
-     * Check if a string is empty.
+     * Check if a string is empty or contains only whitespace characters.
+     *
+     * @param value - The string to check
+     *
+     * @example
+     * stringHelpers.isEmpty('')      // true
+     * stringHelpers.isEmpty('   ')   // true
+     * stringHelpers.isEmpty('hello') // false
      */
     isEmpty(value: string): boolean;
     /**
-     * Escape HTML entities
+     * Escape HTML entities to prevent XSS attacks and display HTML safely.
+     *
+     * @param value - The string to escape
+     * @param options - Escaping options
+     * @param options.encodeSymbols - Whether to encode symbols as HTML entities
+     *
+     * @example
+     * stringHelpers.escapeHTML('<script>alert("xss")</script>')
+     * // '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+     *
+     * @example
+     * stringHelpers.escapeHTML('© 2023', { encodeSymbols: true })
+     * // '&copy; 2023'
      */
     escapeHTML(value: string, options?: {
         encodeSymbols?: boolean;
     }): string;
     /**
-     * Encode symbols to html entities
+     * Encode Unicode symbols and special characters as HTML entities.
+     *
+     * @param value - The string containing symbols to encode
+     * @param options - Encoding options from the 'he' library
+     *
+     * @example
+     * stringHelpers.encodeSymbols('© 2023 AdonisJS ™')
+     * // '&copy; 2023 AdonisJS &trade;'
+     *
+     * @example
+     * stringHelpers.encodeSymbols('Café', { decimal: true })
+     * // 'Caf&#233;'
      */
     encodeSymbols(value: string, options?: EncodeOptions): string;
 };

package/build/src/helpers/string.js

@@ -6,12 +6,25 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import he from 'he';
 import prettyHrTime from 'pretty-hrtime';
 import string from '@poppinss/utils/string';
+import he from 'he';
 import StringBuilder from '@poppinss/utils/string_builder';
 /**
- * Collection of string helpers to transform a string value.
+ * Collection of string helpers to transform a string value. This object extends
+ * the base string utilities from @poppinss/utils with additional AdonisJS-specific
+ * string manipulation methods.
+ *
+ * @example
+ * // Basic string transformations
+ * stringHelpers.camelCase('hello_world') // 'helloWorld'
+ * stringHelpers.snakeCase('HelloWorld')   // 'hello_world'
+ * stringHelpers.pascalCase('hello world') // 'HelloWorld'
+ *
+ * @example
+ * // HTML escaping and encoding
+ * stringHelpers.escapeHTML('<script>alert("xss")</script>')
+ * stringHelpers.encodeSymbols('© 2023 AdonisJS')
  */
 const stringHelpers = {
     ...string,
@@ -21,6 +34,12 @@ const stringHelpers = {
     create(value) {
         return new StringBuilder(value);
     },
+    /**
+     * Formats Node.js hrtime output into a human-readable string.
+     *
+     * @param time - Tuple of [seconds, nanoseconds] from process.hrtime()
+     * @param options - Formatting options for output style and precision
+     */
     prettyHrTime(time, options) {
         return prettyHrTime(time, options);
     },

package/build/src/helpers/types.d.ts

@@ -1,9 +1,23 @@
 /**
  * @deprecated
- * Use "is" helpers instead. The types helpers exists
- * for backward compatibility
+ * Use "is" helpers instead. The types helpers exist for backward compatibility.
+ *
+ * @example
+ * // Instead of using types helpers (deprecated)
+ * types.isString('hello')
+ * types.isNumber(42)
+ *
+ * @example
+ * // Use the new "is" helpers
+ * import { is } from '@adonisjs/core/helpers'
+ * is.string('hello')
+ * is.number(42)
  */
 declare const types: {
+    /**
+     * Direct reference to the is utility for type checking lookups.
+     * @deprecated Use the is helpers directly instead
+     */
     lookup: ((value: unknown) => import("@sindresorhus/is").TypeName) & {
         all: typeof import("@sindresorhus/is").isAll;
         any: typeof import("@sindresorhus/is").isAny;
@@ -90,6 +104,7 @@ declare const types: {
         urlInstance: typeof import("@sindresorhus/is").isUrlInstance;
         urlSearchParams: typeof import("@sindresorhus/is").isUrlSearchParams;
         urlString: typeof import("@sindresorhus/is").isUrlString;
+        optional: typeof import("@sindresorhus/is").isOptional;
         validDate: typeof import("@sindresorhus/is").isValidDate;
         validLength: typeof import("@sindresorhus/is").isValidLength;
         weakMap: typeof import("@sindresorhus/is").isWeakMap;
@@ -97,21 +112,101 @@ declare const types: {
         weakSet: typeof import("@sindresorhus/is").isWeakSet;
         whitespaceString: typeof import("@sindresorhus/is").isWhitespaceString;
     };
+    /**
+     * Check if value is null.
+     * @deprecated Use is.null instead
+     */
     isNull: typeof import("@sindresorhus/is").isNull;
+    /**
+     * Check if value is a boolean.
+     * @deprecated Use is.boolean instead
+     */
     isBoolean: typeof import("@sindresorhus/is").isBoolean;
+    /**
+     * Check if value is a Buffer.
+     * @deprecated Use is.buffer instead
+     */
     isBuffer: typeof import("@sindresorhus/is").isBuffer;
+    /**
+     * Check if value is a number.
+     * @deprecated Use is.number instead
+     */
     isNumber: typeof import("@sindresorhus/is").isNumber;
+    /**
+     * Check if value is a string.
+     * @deprecated Use is.string instead
+     */
     isString: typeof import("@sindresorhus/is").isString;
+    /**
+     * Check if value is an arguments object.
+     * @deprecated Use is.arguments instead
+     */
     isArguments: any;
+    /**
+     * Check if value is an object.
+     * @deprecated Use is.object instead
+     */
     isObject: typeof import("@sindresorhus/is").isObject;
+    /**
+     * Check if value is a Date.
+     * @deprecated Use is.date instead
+     */
     isDate: typeof import("@sindresorhus/is").isDate;
+    /**
+     * Check if value is an array.
+     * @deprecated Use is.array instead
+     */
     isArray: typeof import("@sindresorhus/is").isArray;
+    /**
+     * Check if value is a regular expression.
+     * @deprecated Use is.regExp instead
+     */
     isRegexp: typeof import("@sindresorhus/is").isRegExp;
+    /**
+     * Check if value is an error object.
+     * @deprecated Use is.error instead
+     */
     isError: typeof import("@sindresorhus/is").isError;
+    /**
+     * Check if value is a function.
+     * @deprecated Use is.function instead
+     */
     isFunction: typeof import("@sindresorhus/is").isFunction;
+    /**
+     * Check if value is a class.
+     * @deprecated Use is.class instead
+     */
     isClass: typeof import("@sindresorhus/is").isClass;
+    /**
+     * Check if value is an integer.
+     * @deprecated Use is.integer instead
+     */
     isInteger: typeof import("@sindresorhus/is").isInteger;
+    /**
+     * Check if a number is a float (has decimal places).
+     *
+     * @param value - The number to check
+     * @deprecated Use is.decimal or custom logic instead
+     *
+     * @example
+     * types.isFloat(3.14) // true
+     * types.isFloat(42)   // false
+     */
     isFloat(value: number): value is number;
+    /**
+     * Check if a value represents a decimal number with specific decimal places.
+     *
+     * @param value - The value to check (string or number)
+     * @param options - Options for decimal validation
+     * @param options.decimalPlaces - Regex pattern for allowed decimal places (default: '1,')
+     * @deprecated Use a validation library like Vine or custom logic instead
+     *
+     * @example
+     * types.isDecimal('3.14')     // true
+     * types.isDecimal('42.0')     // true
+     * types.isDecimal('42')       // false
+     * types.isDecimal('3.141', { decimalPlaces: '1,3' }) // true
+     */
     isDecimal(value: string | number, options?: {
         decimalPlaces?: string;
     }): boolean;

package/build/src/helpers/types.js

@@ -9,28 +9,122 @@
 import is from '@sindresorhus/is';
 /**
  * @deprecated
- * Use "is" helpers instead. The types helpers exists
- * for backward compatibility
+ * Use "is" helpers instead. The types helpers exist for backward compatibility.
+ *
+ * @example
+ * // Instead of using types helpers (deprecated)
+ * types.isString('hello')
+ * types.isNumber(42)
+ *
+ * @example
+ * // Use the new "is" helpers
+ * import { is } from '@adonisjs/core/helpers'
+ * is.string('hello')
+ * is.number(42)
  */
 const types = {
+    /**
+     * Direct reference to the is utility for type checking lookups.
+     * @deprecated Use the is helpers directly instead
+     */
     lookup: is,
+    /**
+     * Check if value is null.
+     * @deprecated Use is.null instead
+     */
     isNull: is.null,
+    /**
+     * Check if value is a boolean.
+     * @deprecated Use is.boolean instead
+     */
     isBoolean: is.boolean,
+    /**
+     * Check if value is a Buffer.
+     * @deprecated Use is.buffer instead
+     */
     isBuffer: is.buffer,
+    /**
+     * Check if value is a number.
+     * @deprecated Use is.number instead
+     */
     isNumber: is.number,
+    /**
+     * Check if value is a string.
+     * @deprecated Use is.string instead
+     */
     isString: is.string,
+    /**
+     * Check if value is an arguments object.
+     * @deprecated Use is.arguments instead
+     */
     isArguments: is.arguments,
+    /**
+     * Check if value is an object.
+     * @deprecated Use is.object instead
+     */
     isObject: is.object,
+    /**
+     * Check if value is a Date.
+     * @deprecated Use is.date instead
+     */
     isDate: is.date,
+    /**
+     * Check if value is an array.
+     * @deprecated Use is.array instead
+     */
     isArray: is.array,
+    /**
+     * Check if value is a regular expression.
+     * @deprecated Use is.regExp instead
+     */
     isRegexp: is.regExp,
+    /**
+     * Check if value is an error object.
+     * @deprecated Use is.error instead
+     */
     isError: is.error,
+    /**
+     * Check if value is a function.
+     * @deprecated Use is.function instead
+     */
     isFunction: is.function,
+    /**
+     * Check if value is a class.
+     * @deprecated Use is.class instead
+     */
     isClass: is.class,
+    /**
+     * Check if value is an integer.
+     * @deprecated Use is.integer instead
+     */
     isInteger: is.integer,
+    /**
+     * Check if a number is a float (has decimal places).
+     *
+     * @param value - The number to check
+     * @deprecated Use is.decimal or custom logic instead
+     *
+     * @example
+     * types.isFloat(3.14) // true
+     * types.isFloat(42)   // false
+     */
     isFloat(value) {
         return value !== (value | 0);
     },
+    /**
+     * Check if a value represents a decimal number with specific decimal places.
+     *
+     * @param value - The value to check (string or number)
+     * @param options - Options for decimal validation
+     * @param options.decimalPlaces - Regex pattern for allowed decimal places (default: '1,')
+     * @deprecated Use a validation library like Vine or custom logic instead
+     *
+     * @example
+     * types.isDecimal('3.14')     // true
+     * types.isDecimal('42.0')     // true
+     * types.isDecimal('42')       // false
+     * types.isDecimal('3.141', { decimalPlaces: '1,3' }) // true
+     */
     isDecimal(value, options) {
         if (typeof value === 'number') {
             value = value.toString();