@adonisjs/assembler 8.0.0-next.3 → 8.0.0-next.30

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

@@ -1,45 +1,115 @@
+/**
+ * Represents a controller that has been scanned and analyzed by the routes scanner.
+ * Contains metadata about the controller class and the specific method being called.
+ *
+ * @example
+ * const controller: ScannedController = {
+ *   name: 'UsersController',
+ *   path: '/project/app/controllers/users_controller.ts',
+ *   method: 'index',
+ *   import: {
+ *     type: 'default',
+ *     specifier: '#controllers/users_controller',
+ *     value: 'UsersController'
+ *   }
+ * }
+ */
 export type ScannedController = {
+    /** The name of the controller class */
     name: string;
+    /** Absolute file path to the controller */
     path: string;
+    /** The method name being called on the controller */
     method: string;
+    /** Import information for the controller */
     import: {
+        /** Import type (always 'default' for controllers) */
         type: 'default';
+        /** Import specifier used to import the controller */
         specifier: string;
+        /** The imported value name */
         value: string;
     };
 };
+/**
+ * Represents a validator that has been extracted from controller methods.
+ * Contains information about how the validator is imported and used.
+ *
+ * @example
+ * const validator: ScannedValidator = {
+ *   name: 'createUserValidator',
+ *   import: {
+ *     type: 'named',
+ *     specifier: '#validators/user_validators',
+ *     value: 'createUserValidator'
+ *   }
+ * }
+ */
 export type ScannedValidator = {
+    /** The name/identifier of the validator */
     name: string;
+    /** Import information for the validator */
     import: {
+        /** The type of import (namespace, default, or named) */
         type: 'namespace' | 'default' | 'named';
+        /** The module specifier being imported from */
         specifier: string;
+        /** The imported value name */
         value: string;
     };
 };
 /**
- * Output of scanned route
+ * Output of a scanned route containing all extracted metadata including
+ * controller information, validators, request/response types, and route patterns.
+ *
+ * @example
+ * const scannedRoute: ScannedRoute = {
+ *   name: 'users.store',
+ *   methods: ['POST'],
+ *   domain: 'root',
+ *   pattern: '/users',
+ *   tokens: [{ val: '/users', old: '/users', type: 0, end: '' }],
+ *   request: {
+ *     type: 'InferInput<typeof createUserValidator>',
+ *     imports: ['import { InferInput } from "@vinejs/vine/types"']
+ *   },
+ *   response: {
+ *     type: 'ReturnType<UsersController["store"]>',
+ *     imports: []
+ *   },
+ *   validators: [{
+ *     name: 'createUserValidator',
+ *     import: { type: 'named', specifier: '#validators/user', value: 'createUserValidator' }
+ *   }],
+ *   controller: {
+ *     name: 'UsersController',
+ *     method: 'store',
+ *     path: '/app/controllers/users_controller.ts',
+ *     import: { type: 'default', specifier: '#controllers/users_controller', value: 'UsersController' }
+ *   }
+ * }
  */
 export type ScannedRoute = {
     /**
-     * A unique name for the route provided by AdonisJS http-server. It
-     * could be duplicate across domains.
+     * A unique name for the route provided by AdonisJS http-server.
+     * May be duplicate across different domains.
      */
     name: string;
     /**
-     * HTTP methods for which the route is defined
+     * HTTP methods for which the route is defined (GET, POST, PUT, etc.)
      */
     methods: string[];
     /**
-     * HTTP method for which the route is defined
+     * The domain on which the route is registered (typically 'root')
      */
     domain: string;
     /**
-     * The route pattern
+     * The route pattern with parameter placeholders (e.g., '/users/:id')
      */
     pattern: string;
     /**
-     * Route tokens could be used for constructing a URI for
-     * the route without parsing the pattern
+     * Route tokens that can be used for constructing URIs without parsing the pattern.
+     * Contains information about static and dynamic segments.
      */
     tokens: {
         val: string;
@@ -48,44 +118,70 @@ export type ScannedRoute = {
         end: string;
     }[];
     /**
-     * Inferred request data accepted by the route. By default, the request
-     * data type is inferred when route is using a controller with a
-     * validator
+     * Inferred request data type accepted by the route.
+     * Generated when the route uses a controller with validators.
      */
     request?: {
+        /** TypeScript type definition for the request data */
         type: string;
+        /** Import statements needed for the type definition */
         imports: string[];
     };
     /**
-     * Inferred response for the route. By default, the response is only
-     * inferred when the route is using a controller.
+     * Inferred response type returned by the route.
+     * Generated when the route uses a controller method.
      */
     response?: {
+        /** TypeScript type definition for the response data */
         type: string;
+        /** Import statements needed for the type definition */
         imports: string[];
     };
     /**
-     * Extracted validators info, only when using the controller.
+     * Extracted validator information from the controller method.
+     * Only present when using controller-based routes with validation.
      */
     validators?: ScannedValidator[];
     /**
-     * Extracted controller info, only when using the controller.
+     * Extracted controller information including class and method details.
+     * Only present when using controller-based routes.
      */
     controller?: ScannedController;
 };
 /**
- * The route accepted by the routes scanner when initiating
- * the scanning process.
+ * The route data structure accepted by the routes scanner when initiating
+ * the scanning process. This represents the raw route definition before analysis.
+ *
+ * @example
+ * const routeItem: RoutesListItem = {
+ *   name: 'users.store',
+ *   pattern: '/users',
+ *   domain: 'root',
+ *   methods: ['POST'],
+ *   controllerReference: {
+ *     importExpression: "() => import('#controllers/users_controller')",
+ *     method: 'store'
+ *   },
+ *   tokens: [{ val: '/users', old: '/users', type: 0, end: '' }]
+ * }
  */
 export type RoutesListItem = {
+    /** Optional unique name for the route */
     name?: string;
+    /** Route pattern with parameter placeholders */
     pattern: string;
+    /** Domain on which the route is registered */
     domain: string;
+    /** HTTP methods accepted by this route */
     methods: string[];
-    controllerReference?: {
-        importExpression: string;
-        method?: string;
+    /** Handler information for controller-based routes */
+    handler?: {
+        /** The method name to be called on the controller */
+        method: string;
+        /** Dynamic import expression that loads the controller module */
+        importExpression: string | null;
     };
+    /** Parsed route tokens for URI construction */
     tokens: {
         val: string;
         old: string;
@@ -94,22 +190,56 @@ export type RoutesListItem = {
     }[];
 };
 /**
- * Rules accepted by the route scanner.
+ * A filter function to exclude routes from being processed by the routes scanner.
+ * Return false to filter out (exclude) the route, or true to include it.
+ *
+ * @example
+ * const filterFn: RoutesScannerFilterFn = (route) => {
+ *   // Exclude all admin routes
+ *   if (route.pattern.startsWith('/admin')) {
+ *     return false
+ *   }
+ *
+ *   // Exclude health check routes
+ *   if (route.name === 'health.check') {
+ *     return false
+ *   }
+ *
+ *   // Include all other routes
+ *   return true
+ * }
+ */
+export type RoutesScannerFilterFn = (route: RoutesListItem) => boolean;
+/**
+ * Configuration rules accepted by the routes scanner to customize
+ * the scanning behavior and override type inference.
+ *
+ * @example
+ * const rules: RoutesScannerRules = {
+ *   skip: ['admin.dashboard', 'health.check'],
+ *   response: {
+ *     'users.index': {
+ *       type: 'PaginatedResponse<User[]>',
+ *       imports: ['import { User } from "#models/user"']
+ *     }
+ *   },
+ *   request: {
+ *     'users.store': {
+ *       type: 'CreateUserRequest',
+ *       imports: ['import { CreateUserRequest } from "#types/requests"']
+ *     }
+ *   }
+ * }
  */
 export type RoutesScannerRules = {
     /**
-     * An array of route names or controller+method paths to skip from
-     * the processing
-     */
-    skip: string[];
-    /**
-     * Define custom response type for a route by its name or the
-     * controller+method path
+     * Define custom response types for specific routes by their name
+     * or controller+method path. Overrides automatic type inference.
      */
     response: Record<string, ScannedRoute['response']>;
     /**
-     * Define custom request data type for a route by its name
-     * or the controller+method path
+     * Define custom request data types for specific routes by their name
+     * or controller+method path. Overrides automatic type inference.
      */
     request: Record<string, ScannedRoute['response']>;
 };

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

@@ -1,61 +1,111 @@
 /**
- * Entry to add a middleware to a given middleware stack
- * via the CodeTransformer
+ * Entry to add a middleware to a given middleware stack via the CodeTransformer.
+ * Represents middleware configuration for server, router, or named middleware stacks.
+ *
+ * @example
+ * const corsMiddleware: MiddlewareNode = {
+ *   path: '@adonisjs/cors/cors_middleware',
+ *   position: 'before'
+ * }
+ *
+ * const namedMiddleware: MiddlewareNode = {
+ *   name: 'auth',
+ *   path: '#middleware/auth_middleware',
+ *   position: 'after'
+ * }
  */
 export type MiddlewareNode = {
     /**
-     * If you are adding a named middleware, then you must
-     * define the name.
+     * Required for named middleware. The key name under which the middleware
+     * will be registered in the named middleware collection.
      */
     name?: string;
     /**
-     * The path to the middleware file
+     * The import path to the middleware file. Can be a package import,
+     * subpath import, or relative path.
      *
      * @example
-     *  `@adonisjs/static/static_middleware`
-     *  `#middlewares/silent_auth.js`
+     * '@adonisjs/static/static_middleware'
+     * '#middlewares/silent_auth'
+     * './middleware/custom_middleware.js'
      */
     path: string;
     /**
-     * The position to add the middleware. If `before`
-     * middleware will be added at the first position and
-     * therefore will be run before all others
+     * The position to add the middleware in the stack.
+     * 'before' adds at the beginning (runs first), 'after' adds at the end (runs last).
      *
      * @default 'after'
      */
     position?: 'before' | 'after';
 };
 /**
- * Policy node to be added to the list of policies.
+ * Policy node to be added to the list of Bouncer authorization policies.
+ * Used for registering policies in the application's policy registry.
+ *
+ * @example
+ * const userPolicy: BouncerPolicyNode = {
+ *   name: 'UserPolicy',
+ *   path: '#policies/user_policy'
+ * }
  */
 export type BouncerPolicyNode = {
     /**
-     * Policy name
+     * The name of the policy class (should match the exported class name)
      */
     name: string;
     /**
-     * Policy import path
+     * The import path to the policy file
      */
     path: string;
 };
 /**
- * Defines the structure of an environment variable validation
- * definition
+ * Defines the structure of an environment variable validation definition.
+ * Used to add new environment variable validations to the start/env.ts file.
+ *
+ * @example
+ * const envValidation: EnvValidationNode = {
+ *   leadingComment: 'Database configuration',
+ *   variables: {
+ *     DB_HOST: 'Env.schema.string()',
+ *     DB_PORT: 'Env.schema.number.optional({ port: 5432 })',
+ *     DB_PASSWORD: 'Env.schema.string.optional()'
+ *   }
+ * }
  */
 export type EnvValidationNode = {
     /**
-     * Write a leading comment on top of your variables
+     * Optional leading comment to write above the variable definitions.
+     * Helps group related environment variables together.
      */
     leadingComment?: string;
     /**
-     * A key-value pair of env variables and their validation
+     * A key-value pair of environment variables and their validation schemas.
+     * The key is the environment variable name, the value is the validation code.
      *
      * @example
-     *  MY_VAR: 'Env.schema.string.optional()'
+     * {
+     *   MY_VAR: 'Env.schema.string.optional()',
+     *   API_KEY: 'Env.schema.string()'
+     * }
      */
     variables: Record<string, string>;
 };
+export type HookNode = {
+    type: 'thunk';
+    path: string;
+} | {
+    type: 'import';
+    path: string;
+    name?: string;
+};
 /**
- * The supported package managers for installing packages
+ * The supported package managers for installing packages and managing lockfiles.
+ * Each package manager has specific lockfiles and install commands.
+ *
+ * @example
+ * const packageManager: SupportedPackageManager = 'pnpm'
+ *
+ * // Used in bundler configuration
+ * const bundler = new Bundler(cwd, ts, { packageManager: 'yarn@berry' })
  */
 export type SupportedPackageManager = 'npm' | 'yarn' | 'yarn@berry' | 'pnpm' | 'bun';