@adonisjs/core 6.19.0 → 7.0.0-next.1

package/build/src/test_utils/main.js

@@ -9,14 +9,25 @@
 import { Socket } from 'node:net';
 import Macroable from '@poppinss/macroable';
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { HttpServerUtils } from './http.js';
-import { CookieClient } from '../../modules/http/main.js';
+import { HttpServerUtils } from "./http.js";
+import { CookieClient } from "../../modules/http/main.js";
 /**
  * Test utils has a collection of helper methods to make testing
- * experience great for AdonisJS applications
+ * experience great for AdonisJS applications. It provides utilities
+ * for HTTP testing, context creation, and cookie handling.
+ *
+ * @example
+ * const testUtils = new TestUtils(app)
+ * await testUtils.boot()
+ *
+ * const ctx = await testUtils.createHttpContext()
+ * const httpUtils = testUtils.httpServer()
  */
 export class TestUtils extends Macroable {
     app;
+    /**
+     * Flag to track if test utils have been booted
+     */
     #booted = false;
     /**
      * Check if utils have been booted
@@ -24,6 +35,11 @@ export class TestUtils extends Macroable {
     get isBooted() {
         return this.#booted;
     }
+    /**
+     * Creates a new TestUtils instance
+     *
+     * @param app - The application service instance
+     */
     constructor(app) {
         super();
         this.app = app;
@@ -47,6 +63,8 @@ export class TestUtils extends Macroable {
     }
     /**
      * Create an instance of HTTP context for testing
+     *
+     * @param options - Options for creating HTTP context with custom req/res objects
      */
     async createHttpContext(options = {}) {
         const req = options.req || new IncomingMessage(new Socket());

package/build/src/types.d.ts

@@ -1,40 +1,72 @@
-import type { Repl } from '../modules/repl.js';
-import type { Importer } from '../types/app.js';
-import type { Emitter } from '../modules/events.js';
-import type { Kernel } from '../modules/ace/main.js';
-import type { Application } from '../modules/app.js';
-import type { TestUtils } from './test_utils/main.js';
-import type { HttpServerEvents } from '../types/http.js';
-import type { Dumper } from '../modules/dumper/dumper.js';
-import type { LoggerManager } from '../modules/logger.js';
-import type { HashManager } from '../modules/hash/main.js';
-import type { Encryption } from '../modules/encryption.js';
-import type { ManagerDriverFactory } from '../types/hash.js';
-import type { Router, Server } from '../modules/http/main.js';
-import type { ContainerResolveEventData } from '../types/container.js';
-import type { LoggerConfig, LoggerManagerConfig } from '../types/logger.js';
+import type { Repl } from '../modules/repl.ts';
+import type { Importer } from '../types/app.ts';
+import type { Emitter } from '../modules/events.ts';
+import type { Kernel } from '../modules/ace/main.ts';
+import type { Application } from '../modules/app.ts';
+import type { TestUtils } from './test_utils/main.ts';
+import type { HttpServerEvents, LookupList, RoutesList, SignedURLOptions, UrlFor, URLOptions } from '../types/http.ts';
+import type { Dumper } from '../modules/dumper/dumper.ts';
+import type { LoggerManager } from '../modules/logger.ts';
+import type { HashManager } from '../modules/hash/main.ts';
+import type { Encryption } from '../modules/encryption.ts';
+import type { ManagerDriverFactory } from '../types/hash.ts';
+import type { Router, Server } from '../modules/http/main.ts';
+import type { ContainerResolveEventData } from '../types/container.ts';
+import type { LoggerConfig, LoggerManagerConfig } from '../types/logger.ts';
 /**
  * A config provider waits for the application to get booted
  * and then resolves the config. It receives an instance
  * of the application service.
+ *
+ * @template T - The type of configuration object that the provider resolves
+ *
+ * @example
+ * const databaseProvider: ConfigProvider<DatabaseConfig> = {
+ *   type: 'provider',
+ *   resolver: async (app) => {
+ *     return {
+ *       connection: app.env.get('DB_CONNECTION', 'sqlite'),
+ *       host: app.env.get('DB_HOST', 'localhost')
+ *     }
+ *   }
+ * }
  */
 export type ConfigProvider<T> = {
+    /** Identifies this as a config provider */
     type: 'provider';
+    /** Function that resolves the configuration using the application service */
     resolver: (app: ApplicationService) => Promise<T>;
 };
 /**
- * Options accepted by ignitor
+ * Options accepted by ignitor for configuring the application bootstrap process.
+ *
+ * @example
+ * const options: IgnitorOptions = {
+ *   importer: (filePath) => import(filePath)
+ * }
  */
 export type IgnitorOptions = {
+    /** Optional custom importer function for loading modules */
     importer?: Importer;
 };
 /**
  * A list of known events. The interface must be extended in
  * user land code or packages to register events and their
  * types.
+ *
+ * @example
+ * // Extending EventsList in user code
+ * declare module '@adonisjs/core' {
+ *   interface EventsList {
+ *     'user:created': { user: User }
+ *     'order:placed': { orderId: string, amount: number }
+ *   }
+ * }
  */
 export interface EventsList extends HttpServerEvents {
+    /** Event fired when a container binding is resolved */
     'container_binding:resolved': ContainerResolveEventData<ContainerBindings>;
+    /** Event fired when the HTTP server is ready and listening */
     'http:server_ready': {
         port: number;
         host: string;
@@ -43,16 +75,47 @@ export interface EventsList extends HttpServerEvents {
 }
 /**
  * The loggers list inferred from the user application
- * config
+ * config. This interface should be extended in user code
+ * to register custom loggers.
+ *
+ * @example
+ * // Extending LoggersList in user code
+ * declare module '@adonisjs/core' {
+ *   interface LoggersList {
+ *     default: LoggerConfig
+ *     file: LoggerConfig
+ *   }
+ * }
  */
 export interface LoggersList {
 }
+/**
+ * Utility type to infer logger configurations from a LoggerManagerConfig.
+ *
+ * @template T - The logger manager configuration type
+ */
 export type InferLoggers<T extends LoggerManagerConfig<any>> = T['loggers'];
 /**
- * A list of known hashers inferred from the user config
+ * A list of known hashers inferred from the user config.
+ * This interface should be extended in user code to register
+ * custom hashers.
+ *
+ * @example
+ * // Extending HashersList in user code
+ * declare module '@adonisjs/core' {
+ *   interface HashersList {
+ *     scrypt: ManagerDriverFactory
+ *     argon: ManagerDriverFactory
+ *   }
+ * }
  */
 export interface HashersList {
 }
+/**
+ * Utility type to infer hasher configurations from a config provider.
+ *
+ * @template T - The config provider type that resolves to an object with a 'list' property
+ */
 export type InferHashers<T extends ConfigProvider<{
     list: Record<string, ManagerDriverFactory>;
 }>> = Awaited<ReturnType<T['resolver']>>['list'];
@@ -67,58 +130,252 @@ export type InferHashers<T extends ConfigProvider<{
  */
 /**
  * Application service is a singleton resolved from
- * the container
+ * the container. It provides access to the core application
+ * instance with all registered bindings.
+ *
+ * @example
+ * // Accessing application service in a controller
+ * export default class HomeController {
+ *   async index({ app }: { app: ApplicationService }) {
+ *     const version = app.version
+ *     const env = app.env.get('NODE_ENV')
+ *   }
+ * }
  */
 export interface ApplicationService extends Application<ContainerBindings extends Record<any, any> ? ContainerBindings : never> {
 }
 /**
  * Logger service is a singleton logger instance registered
- * to the container.
+ * to the container. It provides access to configured loggers.
+ *
+ * @example
+ * // Using logger service in a controller
+ * export default class UserController {
+ *   async store({ logger }: { logger: LoggerService }) {
+ *     logger.info('Creating new user')
+ *     logger.use('file').error('Failed to create user')
+ *   }
+ * }
  */
 export interface LoggerService extends LoggerManager<LoggersList extends Record<string, LoggerConfig> ? LoggersList : never> {
 }
 /**
  * Emitter service is a singleton emitter instance registered
- * to the container.
+ * to the container. It provides type-safe event emission and listening.
+ *
+ * @example
+ * // Using emitter service to emit events
+ * export default class UserController {
+ *   async store({ emitter }: { emitter: EmitterService }) {
+ *     const user = await User.create(data)
+ *     emitter.emit('user:created', { user })
+ *   }
+ * }
  */
 export interface EmitterService extends Emitter<EventsList> {
 }
 /**
  * Encryption service is a singleton Encryption class instance
- * registered to the container.
+ * registered to the container. It provides encryption and decryption
+ * functionality using the application's secret key.
+ *
+ * @example
+ * // Using encryption service
+ * export default class PaymentController {
+ *   async process({ encryption }: { encryption: EncryptionService }) {
+ *     const encrypted = encryption.encrypt('sensitive-data')
+ *     const decrypted = encryption.decrypt(encrypted)
+ *   }
+ * }
  */
 export interface EncryptionService extends Encryption {
 }
 /**
- * Http server service added to the container as a singleton
+ * Http server service added to the container as a singleton.
+ * It provides access to the HTTP server instance for handling
+ * requests and responses.
+ *
+ * @example
+ * // Accessing server service in middleware
+ * export default class CustomMiddleware {
+ *   async handle({ server }: { server: HttpServerService }, next: NextFn) {
+ *     console.log('Server listening on:', server.getPort())
+ *     return next()
+ *   }
+ * }
  */
 export interface HttpServerService extends Server {
 }
 /**
- * Http server service added to the container as a singleton
+ * Http router service added to the container as a singleton.
+ * It provides access to the application's router for defining
+ * and managing routes.
+ *
+ * @example
+ * // Using router service to define routes programmatically
+ * export default class RouteProvider {
+ *   boot({ router }: { router: HttpRouterService }) {
+ *     router.get('/api/health', () => ({ status: 'ok' }))
+ *   }
+ * }
  */
 export interface HttpRouterService extends Router {
 }
+/**
+ * Url builder service offers a type-safe API for creating URLs
+ * for pre-registered routes. It ensures type safety when building
+ * URLs with parameters.
+ *
+ * @example
+ * // Using URL builder service
+ * export default class PostController {
+ *   async show({ urlBuilder }: { urlBuilder: UrlBuilderService }) {
+ *     const postUrl = urlBuilder.make('posts.show', { id: 1 })
+ *     const userUrl = urlBuilder.make('users.profile', { username: 'john' })
+ *   }
+ * }
+ */
+export interface UrlBuilderService extends UrlFor<RoutesList extends LookupList ? RoutesList : never, URLOptions> {
+}
+/**
+ * Url builder service offers a type-safe API for creating signed URLs
+ * for pre-registered routes. Signed URLs include a signature that prevents
+ * tampering and can have expiration times.
+ *
+ * @example
+ * // Using signed URL builder service
+ * export default class FileController {
+ *   async getDownloadUrl({ signedUrlBuilder }: { signedUrlBuilder: SignedUrlBuilderService }) {
+ *     const signedUrl = signedUrlBuilder.make('files.download',
+ *       { id: 1 },
+ *       { expiresIn: '1h' }
+ *     )
+ *   }
+ * }
+ */
+export interface SignedUrlBuilderService extends UrlFor<RoutesList extends LookupList ? RoutesList : never, SignedURLOptions> {
+}
 /**
  * Hash service is a singleton instance of the HashManager
- * registered in the container
+ * registered in the container. It provides password hashing
+ * and verification functionality.
+ *
+ * @example
+ * // Using hash service for password management
+ * export default class AuthController {
+ *   async register({ hash }: { hash: HashService }) {
+ *     const hashedPassword = await hash.make('user-password')
+ *     const isValid = await hash.verify(hashedPassword, 'user-password')
+ *   }
+ * }
  */
 export interface HashService extends HashManager<HashersList extends Record<string, ManagerDriverFactory> ? HashersList : never> {
 }
 /**
- * A list of known container bindings.
+ * A list of known container bindings. This interface defines
+ * all the services that are registered in the IoC container
+ * and available for dependency injection.
+ *
+ * @example
+ * // Accessing container bindings in a service
+ * export default class UserService {
+ *   constructor(
+ *     private logger: LoggerService,
+ *     private hash: HashService,
+ *     private emitter: EmitterService
+ *   ) {}
+ * }
  */
 export interface ContainerBindings {
+    /** Ace command-line kernel */
     ace: Kernel;
+    /** Database query dumper */
     dumper: Dumper;
+    /** Main application instance */
     app: ApplicationService;
+    /** Logger manager instance */
     logger: LoggerService;
+    /** Application configuration */
     config: ApplicationService['config'];
+    /** Event emitter instance */
     emitter: EmitterService;
+    /** Encryption service */
     encryption: EncryptionService;
+    /** Hash manager for password hashing */
     hash: HashService;
+    /** HTTP server instance */
     server: HttpServerService;
+    /** HTTP router instance */
     router: HttpRouterService;
+    /** Test utilities */
     testUtils: TestUtils;
+    /** REPL instance */
     repl: Repl;
 }
+/**
+ * Configuration options for the IndexEntities assembler hook.
+ * This type defines the settings for automatically generating
+ * barrel files for controllers, listeners, and events.
+ *
+ * @example
+ * // Basic configuration
+ * const config: IndexEntitiesConfig = {
+ *   controllers: { enabled: true },
+ *   events: { source: 'app/custom-events' }
+ * }
+ *
+ * @example
+ * // Detailed configuration with custom paths
+ * const config: IndexEntitiesConfig = {
+ *   controllers: {
+ *     enabled: true,
+ *     source: 'app/http/controllers',
+ *     importAlias: '#controllers',
+ *     glob: ['**\/*_controller.ts']
+ *   },
+ *   listeners: {
+ *     enabled: false
+ *   }
+ * }
+ */
+export type IndexEntitiesConfig = {
+    /** Configuration for controllers indexing */
+    controllers?: {
+        /** Whether to enable controllers indexing */
+        enabled?: boolean;
+        /** Source directory for controllers */
+        source?: string;
+        /** Import alias for controllers */
+        importAlias?: string;
+        /** Glob patterns for matching controller files */
+        glob?: string[];
+    };
+    /** Configuration for listeners indexing */
+    listeners?: {
+        /** Whether to enable listeners indexing */
+        enabled?: boolean;
+        /** Source directory for listeners */
+        source?: string;
+        /** Import alias for listeners */
+        importAlias?: string;
+        /** Glob patterns for matching listener files */
+        glob?: string[];
+    };
+    /** Configuration for events indexing */
+    events?: {
+        /** Whether to enable events indexing */
+        enabled?: boolean;
+        /** Source directory for events */
+        source?: string;
+        /** Import alias for events */
+        importAlias?: string;
+        /** Glob patterns for matching event files */
+        glob?: string[];
+    };
+    transformers?: {
+        enabled?: boolean;
+        source?: string;
+        importAlias?: string;
+        glob?: string[];
+    };
+};

package/build/src/utils.d.ts

@@ -0,0 +1,60 @@
+import type typescript from 'typescript';
+import type * as Assembler from '@adonisjs/assembler';
+import { type RecursiveFileTree } from '@adonisjs/assembler/types';
+import { type ApplicationService } from './types.ts';
+/**
+ * Imports the AdonisJS assembler package optionally. This function attempts
+ * to import the assembler and returns undefined if it's not available,
+ * making it safe to use in environments where the assembler might not be installed.
+ *
+ * @param app - The application service instance used for importing the assembler
+ *
+ * @example
+ * const assembler = await importAssembler(app)
+ * if (assembler) {
+ *   // Use assembler functionality
+ *   const generator = new assembler.IndexGenerator()
+ * }
+ */
+export declare function importAssembler(app: ApplicationService): Promise<typeof Assembler | undefined>;
+/**
+ * Imports the TypeScript compiler package optionally. This function attempts
+ * to import TypeScript and returns undefined if it's not available,
+ * making it safe to use in environments where TypeScript might not be installed.
+ *
+ * @param app - The application service instance used for importing TypeScript
+ *
+ * @example
+ * const ts = await importTypeScript(app)
+ * if (ts) {
+ *   // Use TypeScript compiler API
+ *   const program = ts.createProgram(['file.ts'], {})
+ *   const sourceFile = program.getSourceFile('file.ts')
+ * }
+ */
+export declare function importTypeScript(app: ApplicationService): Promise<typeof typescript | undefined>;
+/**
+ * Outputs transformer data objects by generating TypeScript type definitions
+ * for all transformers in the provided file tree. This function creates
+ * InferData types for each transformer and organizes them in namespaces.
+ *
+ * @param transformersList - A recursive file tree containing transformer file paths
+ * @param buffer - The file buffer to write the generated types to
+ *
+ * @example
+ * const transformersList = {
+ *   User: '#app/transformers/user_transformer',
+ *   Auth: {
+ *     Login: '#app/transformers/auth/login_transformer'
+ *   }
+ * }
+ * await outputTransformerDataObjects(transformersList, buffer)
+ * // Generates:
+ * // export namespace Data {
+ * //   export type User = InferData<UserTransformer>
+ * //   export namespace Auth {
+ * //     export type Login = InferData<AuthLoginTransformer>
+ * //   }
+ * // }
+ */
+export declare function outputTransformerDataObjects(transformersList: RecursiveFileTree, buffer: Assembler.FileBuffer): Promise<void>;

package/build/src/utils.js

@@ -0,0 +1,104 @@
+/*
+ * @adonisjs/core
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * Imports the AdonisJS assembler package optionally. This function attempts
+ * to import the assembler and returns undefined if it's not available,
+ * making it safe to use in environments where the assembler might not be installed.
+ *
+ * @param app - The application service instance used for importing the assembler
+ *
+ * @example
+ * const assembler = await importAssembler(app)
+ * if (assembler) {
+ *   // Use assembler functionality
+ *   const generator = new assembler.IndexGenerator()
+ * }
+ */
+export async function importAssembler(app) {
+    try {
+        return await app.import('@adonisjs/assembler');
+    }
+    catch { }
+}
+/**
+ * Imports the TypeScript compiler package optionally. This function attempts
+ * to import TypeScript and returns undefined if it's not available,
+ * making it safe to use in environments where TypeScript might not be installed.
+ *
+ * @param app - The application service instance used for importing TypeScript
+ *
+ * @example
+ * const ts = await importTypeScript(app)
+ * if (ts) {
+ *   // Use TypeScript compiler API
+ *   const program = ts.createProgram(['file.ts'], {})
+ *   const sourceFile = program.getSourceFile('file.ts')
+ * }
+ */
+export async function importTypeScript(app) {
+    try {
+        return await app.importDefault('typescript');
+    }
+    catch { }
+}
+/**
+ * Outputs transformer data objects by generating TypeScript type definitions
+ * for all transformers in the provided file tree. This function creates
+ * InferData types for each transformer and organizes them in namespaces.
+ *
+ * @param transformersList - A recursive file tree containing transformer file paths
+ * @param buffer - The file buffer to write the generated types to
+ *
+ * @example
+ * const transformersList = {
+ *   User: '#app/transformers/user_transformer',
+ *   Auth: {
+ *     Login: '#app/transformers/auth/login_transformer'
+ *   }
+ * }
+ * await outputTransformerDataObjects(transformersList, buffer)
+ * // Generates:
+ * // export namespace Data {
+ * //   export type User = InferData<UserTransformer>
+ * //   export namespace Auth {
+ * //     export type Login = InferData<AuthLoginTransformer>
+ * //   }
+ * // }
+ */
+export async function outputTransformerDataObjects(transformersList, buffer) {
+    const importsBuffer = buffer.create();
+    importsBuffer.write(`import { InferData } from '@adonisjs/core/types/transformers'`);
+    buffer.writeLine(importsBuffer);
+    buffer.write('export namespace Data {').indent();
+    /**
+     * Recursively generates namespace tree structure for transformers.
+     * Creates nested namespaces for directory structures and type exports
+     * for individual transformer files.
+     *
+     * @param input - The current level of the file tree to process
+     * @param parents - Array of parent namespace names for import naming
+     */
+    function generateNamespaceTree(input, parents) {
+        Object.keys(input).forEach((key) => {
+            const value = input[key];
+            if (typeof value === 'string') {
+                const importName = `${parents.join()}${key}Transformer`;
+                importsBuffer.write(`import ${importName} from '${value}'`);
+                buffer.write(`export type ${key} = InferData<${importName}>`);
+            }
+            else {
+                buffer.write(`export namespace ${key} {`).indent();
+                generateNamespaceTree(value, [...parents, key]);
+                buffer.dedent().write(`}`);
+            }
+        });
+    }
+    generateNamespaceTree(transformersList, []);
+    buffer.dedent().write('}');
+}

package/build/src/vine.d.ts

@@ -8,12 +8,35 @@ declare const MULTIPART_FILE: typeof symbols.SUBTYPE;
 export type FileRuleValidationOptions = Partial<FileValidationOptions> | ((field: FieldContext) => Partial<FileValidationOptions>);
 /**
  * Represents a multipart file uploaded via multipart/form-data HTTP
- * request.
+ * request. This class extends VineJS's BaseLiteralType to provide
+ * specialized validation for uploaded files.
+ *
+ * @example
+ * const fileSchema = vine.object({
+ *   avatar: vine.file({
+ *     size: '2mb',
+ *     extnames: ['jpg', 'png']
+ *   })
+ * })
  */
 export declare class VineMultipartFile extends BaseLiteralType<MultipartFile, MultipartFile, MultipartFile> {
     #private;
+    /**
+     * Symbol identifier for multipart file subtype
+     */
     [MULTIPART_FILE]: string;
+    /**
+     * Creates a new VineMultipartFile instance
+     *
+     * @param validationOptions - File validation options like size limits and allowed extensions
+     * @param options - Field options from VineJS
+     * @param validations - Array of validation functions to apply
+     */
     constructor(validationOptions?: FileRuleValidationOptions, options?: FieldOptions, validations?: Validation<any>[]);
+    /**
+     * Creates a clone of the current VineMultipartFile instance
+     * with the same validation options and configurations
+     */
     clone(): this;
 }
 export {};

package/build/src/vine.js

@@ -56,15 +56,41 @@ const isMultipartFile = vine.createRule((file, options, field) => {
 });
 /**
  * Represents a multipart file uploaded via multipart/form-data HTTP
- * request.
+ * request. This class extends VineJS's BaseLiteralType to provide
+ * specialized validation for uploaded files.
+ *
+ * @example
+ * const fileSchema = vine.object({
+ *   avatar: vine.file({
+ *     size: '2mb',
+ *     extnames: ['jpg', 'png']
+ *   })
+ * })
  */
 export class VineMultipartFile extends BaseLiteralType {
+    /**
+     * Private validation options for file validation
+     */
     #validationOptions;
+    /**
+     * Symbol identifier for multipart file subtype
+     */
     [MULTIPART_FILE] = 'multipartFile';
+    /**
+     * Creates a new VineMultipartFile instance
+     *
+     * @param validationOptions - File validation options like size limits and allowed extensions
+     * @param options - Field options from VineJS
+     * @param validations - Array of validation functions to apply
+     */
     constructor(validationOptions, options, validations) {
         super(options, validations || [isMultipartFile(validationOptions || {})]);
         this.#validationOptions = validationOptions;
     }
+    /**
+     * Creates a clone of the current VineMultipartFile instance
+     * with the same validation options and configurations
+     */
     clone() {
         return new VineMultipartFile(this.#validationOptions, this.cloneOptions(), this.cloneValidations());
     }