@angular/compiler-cli 17.3.1 → 17.3.2

package/index.d.ts

@@ -13,4 +13,5 @@ export { OptimizeFor } from './src/ngtsc/typecheck/api';
 export { ConsoleLogger, Logger, LogLevel } from './src/ngtsc/logging';
 export { NodeJSFileSystem } from './src/ngtsc/file_system';
 export * from './src/ngtsc/docs/src/entities';
+export * from './src/ngtsc/docs';
 export { isLocalCompilationDiagnostics } from './src/ngtsc/diagnostics';

package/linker/src/file_linker/partial_linkers/util.d.ts

@@ -7,7 +7,7 @@
  */
 import { MaybeForwardRefExpression, outputAst as o, R3DeclareDependencyMetadata, R3DependencyMetadata, R3Reference } from '@angular/compiler';
 import { AstObject, AstValue } from '../../ast/ast_value';
-export declare const PLACEHOLDER_VERSION = "17.3.1";
+export declare const PLACEHOLDER_VERSION = "17.3.2";
 export declare const SHOULD_USE_TEMPLATE_PIPELINE_FOR_LINKER = true;
 export declare function wrapReference<TExpression>(wrapped: o.WrappedNodeExpr<TExpression>): R3Reference;
 /**

package/linker/src/file_linker/translator.d.ts

@@ -17,9 +17,9 @@ export declare class Translator<TStatement, TExpression> {
     /**
      * Translate the given output AST in the context of an expression.
      */
-    translateExpression(expression: o.Expression, imports: ImportGenerator<TExpression>, options?: TranslatorOptions<TExpression>): TExpression;
+    translateExpression(expression: o.Expression, imports: ImportGenerator<null, TExpression>, options?: TranslatorOptions<TExpression>): TExpression;
     /**
      * Translate the given output AST in the context of a statement.
      */
-    translateStatement(statement: o.Statement, imports: ImportGenerator<TExpression>, options?: TranslatorOptions<TExpression>): TStatement;
+    translateStatement(statement: o.Statement, imports: ImportGenerator<null, TExpression>, options?: TranslatorOptions<TExpression>): TStatement;
 }

package/linker/src/linker_import_generator.d.ts

@@ -5,7 +5,7 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.io/license
  */
-import { ImportGenerator, NamedImport } from '../../src/ngtsc/translator';
+import { AstFactory, ImportGenerator, ImportRequest } from '../../src/ngtsc/translator';
 /**
  * A class that is used to generate imports when translating from Angular Output AST to an AST to
  * render, such as Babel.
@@ -14,10 +14,10 @@ import { ImportGenerator, NamedImport } from '../../src/ngtsc/translator';
  * must be achieved by property access on an `ng` namespace identifier, which is passed in via the
  * constructor.
  */
-export declare class LinkerImportGenerator<TExpression> implements ImportGenerator<TExpression> {
+export declare class LinkerImportGenerator<TStatement, TExpression> implements ImportGenerator<null, TExpression> {
+    private factory;
     private ngImport;
-    constructor(ngImport: TExpression);
-    generateNamespaceImport(moduleName: string): TExpression;
-    generateNamedImport(moduleName: string, originalSymbol: string): NamedImport<TExpression>;
+    constructor(factory: AstFactory<TStatement, TExpression>, ngImport: TExpression);
+    addImport(request: ImportRequest<null>): TExpression;
     private assertModuleName;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/compiler-cli",
-  "version": "17.3.1",
+  "version": "17.3.2",
   "description": "Angular - the compiler CLI for Node.js",
   "typings": "index.d.ts",
   "bin": {
@@ -53,7 +53,7 @@
     "yargs": "^17.2.1"
   },
   "peerDependencies": {
-    "@angular/compiler": "17.3.1",
+    "@angular/compiler": "17.3.2",
     "typescript": ">=5.2 <5.5"
   },
   "repository": {

package/src/ngtsc/annotations/directive/index.d.ts

@@ -12,3 +12,4 @@ export * from './src/input_function';
 export * from './src/output_function';
 export * from './src/query_functions';
 export * from './src/model_function';
+export * from './src/initializer_functions';

package/src/ngtsc/annotations/directive/src/initializer_function_access.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import { ClassMember } from '../../../reflection';
+import { InitializerFunctionMetadata } from './initializer_functions';
+/**
+ * Validates that the initializer member is compatible with the given class
+ * member in terms of field access and visibility.
+ *
+ * @throws {FatalDiagnosticError} If the recognized initializer API is
+ *   incompatible.
+ */
+export declare function validateAccessOfInitializerApiMember({ api, call }: InitializerFunctionMetadata, member: Pick<ClassMember, 'accessLevel'>): void;

package/src/ngtsc/annotations/directive/src/initializer_functions.d.ts

@@ -7,7 +7,7 @@
  */
 import ts from 'typescript';
 import { ImportedSymbolsTracker } from '../../../imports';
-import { ClassMember, ReflectionHost } from '../../../reflection';
+import { ClassMemberAccessLevel, ReflectionHost } from '../../../reflection';
 /**
  * @fileoverview
  *
@@ -20,14 +20,18 @@ import { ClassMember, ReflectionHost } from '../../../reflection';
  * declared through initializer APIs.
  */
 export interface InitializerApiFunction {
+    /** Module name where the initializer function is imported from. */
     owningModule: '@angular/core' | '@angular/core/rxjs-interop';
+    /** Export name of the initializer function. */
     functionName: ('input' | 'model' | 'output' | 'outputFromObservable' | 'viewChild' | 'viewChildren' | 'contentChild' | 'contentChildren');
+    /** Class member access levels compatible with the API. */
+    allowedAccessLevels: ClassMemberAccessLevel[];
 }
 /**
  * Metadata describing an Angular class member that was recognized through
  * a function initializer. Like `input`, `input.required` or `viewChild`.
  */
-interface InitializerFunctionMetadata {
+export interface InitializerFunctionMetadata {
     /** Initializer API function that was recognized. */
     api: InitializerApiFunction;
     /** Node referring to the call expression. */
@@ -36,13 +40,13 @@ interface InitializerFunctionMetadata {
     isRequired: boolean;
 }
 /**
- * Attempts to identify an Angular class member that is declared via
- * its initializer referring to a given initializer API function.
+ * Attempts to identify an Angular initializer function call.
  *
  * Note that multiple possible initializer API function names can be specified,
  * allowing for checking multiple types in one pass.
+ *
+ * @returns The parsed initializer API, or null if none was found.
  */
-export declare function tryParseInitializerApiMember<Functions extends InitializerApiFunction[]>(functions: Functions, member: Pick<ClassMember, 'value'>, reflector: ReflectionHost, importTracker: ImportedSymbolsTracker): (InitializerFunctionMetadata & {
+export declare function tryParseInitializerApi<Functions extends InitializerApiFunction[]>(functions: Functions, expression: ts.Expression, reflector: ReflectionHost, importTracker: ImportedSymbolsTracker): (InitializerFunctionMetadata & {
     api: Functions[number];
 } | null);
-export {};

package/src/ngtsc/annotations/directive/src/input_function.d.ts

@@ -12,4 +12,4 @@ import { ClassMember, ReflectionHost } from '../../../reflection';
  * Attempts to parse a signal input class member. Returns the parsed
  * input mapping if possible.
  */
-export declare function tryParseSignalInputMapping(member: Pick<ClassMember, 'name' | 'value'>, reflector: ReflectionHost, importTracker: ImportedSymbolsTracker): InputMapping | null;
+export declare function tryParseSignalInputMapping(member: Pick<ClassMember, 'name' | 'value' | 'accessLevel'>, reflector: ReflectionHost, importTracker: ImportedSymbolsTracker): InputMapping | null;

package/src/ngtsc/annotations/directive/src/model_function.d.ts

@@ -11,4 +11,4 @@ import { ClassMember, ReflectionHost } from '../../../reflection';
 /**
  * Attempts to parse a model class member. Returns the parsed model mapping if possible.
  */
-export declare function tryParseSignalModelMapping(member: Pick<ClassMember, 'name' | 'value'>, reflector: ReflectionHost, importTracker: ImportedSymbolsTracker): ModelMapping | null;
+export declare function tryParseSignalModelMapping(member: Pick<ClassMember, 'name' | 'value' | 'accessLevel'>, reflector: ReflectionHost, importTracker: ImportedSymbolsTracker): ModelMapping | null;

package/src/ngtsc/annotations/directive/src/output_function.d.ts

@@ -13,7 +13,7 @@ import { ClassMember, ReflectionHost } from '../../../reflection';
  * Attempts to parse a signal output class member. Returns the parsed
  * input mapping if possible.
  */
-export declare function tryParseInitializerBasedOutput(member: Pick<ClassMember, 'name' | 'value'>, reflector: ReflectionHost, importTracker: ImportedSymbolsTracker): {
+export declare function tryParseInitializerBasedOutput(member: Pick<ClassMember, 'name' | 'value' | 'accessLevel'>, reflector: ReflectionHost, importTracker: ImportedSymbolsTracker): {
     call: ts.CallExpression;
     metadata: InputOrOutput;
 } | null;

package/src/ngtsc/annotations/directive/src/query_functions.d.ts

@@ -19,7 +19,7 @@ export type QueryFunctionName = 'viewChild' | 'contentChild' | 'viewChildren' |
  *
  * @returns Resolved query metadata, or null if no query is declared.
  */
-export declare function tryParseSignalQueryFromInitializer(member: Pick<ClassMember, 'name' | 'value'>, reflector: ReflectionHost, importTracker: ImportedSymbolsTracker): {
+export declare function tryParseSignalQueryFromInitializer(member: Pick<ClassMember, 'name' | 'value' | 'accessLevel'>, reflector: ReflectionHost, importTracker: ImportedSymbolsTracker): {
     name: QueryFunctionName;
     metadata: R3QueryMetadata;
     call: ts.CallExpression;

package/src/ngtsc/annotations/index.d.ts

@@ -7,7 +7,7 @@
  */
 export { forwardRefResolver, getAngularDecorators, isAngularDecorator, NoopReferencesRegistry, ReferencesRegistry, ResourceLoader, ResourceLoaderContext } from './common';
 export { ComponentDecoratorHandler } from './component';
-export { DirectiveDecoratorHandler, queryDecoratorNames, QueryFunctionName, tryParseInitializerBasedOutput, tryParseSignalInputMapping, tryParseSignalModelMapping, tryParseSignalQueryFromInitializer } from './directive';
+export { DirectiveDecoratorHandler, InitializerApiFunction, queryDecoratorNames, QueryFunctionName, tryParseInitializerApi, tryParseInitializerBasedOutput, tryParseSignalInputMapping, tryParseSignalModelMapping, tryParseSignalQueryFromInitializer } from './directive';
 export { NgModuleDecoratorHandler } from './ng_module';
 export { InjectableDecoratorHandler } from './src/injectable';
 export { PipeDecoratorHandler } from './src/pipe';

package/src/ngtsc/diagnostics/src/error_code.d.ts

@@ -37,6 +37,11 @@ export declare enum ErrorCode {
      * function, but is still detected unexpectedly.
      */
     INITIALIZER_API_NO_REQUIRED_FUNCTION = 1052,
+    /**
+     * Raised whenever an initializer API is used on a class member
+     * and the given access modifiers (e.g. `private`) are not allowed.
+     */
+    INITIALIZER_API_DISALLOWED_MEMBER_VISIBILITY = 1053,
     /**
      * An Angular feature, like inputs, outputs or queries is incorrectly
      * declared on a static member.

package/src/ngtsc/docs/src/entities.d.ts

@@ -19,7 +19,8 @@ export declare enum EntryType {
     NgModule = "ng_module",
     Pipe = "pipe",
     TypeAlias = "type_alias",
-    UndecoratedClass = "undecorated_class"
+    UndecoratedClass = "undecorated_class",
+    InitializerApiFunction = "initializer_api_function"
 }
 /** Types of class members */
 export declare enum MemberType {
@@ -133,3 +134,37 @@ export interface ParameterEntry {
     isOptional: boolean;
     isRestParam: boolean;
 }
+/** Interface describing a function with overload signatures. */
+export interface FunctionWithOverloads {
+    name: string;
+    signatures: FunctionEntry[];
+    implementation: FunctionEntry | null;
+}
+/**
+ * Docs entry describing an initializer API function.
+ *
+ * An initializer API function is a function that is invoked as
+ * initializer of class members. The function may hold additional
+ * sub functions, like `.required`.
+ *
+ * Known popular initializer APIs are `input()`, `output()`, `model()`.
+ *
+ * Initializer APIs are often constructed typed in complex ways so this
+ * entry type allows for readable "parsing" and interpretation of such
+ * constructs. Initializer APIs are explicitly denoted via a JSDoc tag.
+ */
+export interface InitializerApiFunctionEntry extends DocEntry {
+    callFunction: FunctionWithOverloads;
+    subFunctions: FunctionWithOverloads[];
+    __docsMetadata__?: {
+        /**
+         * Whether types should be shown in the signature
+         * preview of docs.
+         *
+         * By default, for readability purposes, types are omitted, but
+         * shorter initializer API functions like `output` may decide to
+         * render these types.
+         */
+        showTypesInSignaturePreview?: boolean;
+    };
+}

package/src/ngtsc/docs/src/function_extractor.d.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 import ts from 'typescript';
-import { FunctionEntry } from './entities';
+import { FunctionEntry, ParameterEntry } from './entities';
 export type FunctionLike = ts.FunctionDeclaration | ts.MethodDeclaration | ts.MethodSignature | ts.CallSignatureDeclaration | ts.ConstructSignatureDeclaration;
 export declare class FunctionExtractor {
     private name;
@@ -14,8 +14,9 @@ export declare class FunctionExtractor {
     private typeChecker;
     constructor(name: string, declaration: FunctionLike, typeChecker: ts.TypeChecker);
     extract(): FunctionEntry;
-    private extractAllParams;
     /** Gets all overloads for the function (excluding this extractor's FunctionDeclaration). */
     getOverloads(): ts.FunctionDeclaration[];
     private getSymbol;
 }
+/** Extracts parameters of the given parameter declaration AST nodes. */
+export declare function extractAllParams(params: ts.NodeArray<ts.ParameterDeclaration>, typeChecker: ts.TypeChecker): ParameterEntry[];

package/src/ngtsc/docs/src/initializer_api_function_extractor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import ts from 'typescript';
+import { InitializerApiFunctionEntry } from './entities';
+/**
+ * Checks whether the given node corresponds to an initializer API function.
+ *
+ * An initializer API function is a function declaration or variable declaration
+ * that is explicitly annotated with `@initializerApiFunction`.
+ *
+ * Note: The node may be a function overload signature that is automatically
+ * resolved to its implementation to detect the JSDoc tag.
+ */
+export declare function isInitializerApiFunction(node: ts.Node, typeChecker: ts.TypeChecker): node is ts.VariableDeclaration | ts.FunctionDeclaration;
+/**
+ * Extracts the given node as initializer API function and returns
+ * a docs entry that can be rendered to represent the API function.
+ */
+export declare function extractInitializerApiFunction(node: ts.VariableDeclaration | ts.FunctionDeclaration, typeChecker: ts.TypeChecker): InitializerApiFunctionEntry;

package/src/ngtsc/imports/index.d.ts

@@ -12,7 +12,7 @@ export { DeferredSymbolTracker } from './src/deferred_symbol_tracker';
 export { AbsoluteModuleStrategy, assertSuccessfulReferenceEmit, EmittedReference, FailedEmitResult, ImportedFile, ImportFlags, LocalIdentifierStrategy, LogicalProjectStrategy, ReferenceEmitKind, ReferenceEmitResult, ReferenceEmitStrategy, ReferenceEmitter, RelativePathStrategy, UnifiedModulesStrategy } from './src/emitter';
 export { ImportedSymbolsTracker } from './src/imported_symbols_tracker';
 export { LocalCompilationExtraImportsTracker } from './src/local_compilation_extra_imports_tracker';
-export { isAliasImportDeclaration, loadIsReferencedAliasDeclarationPatch } from './src/patch_alias_reference_resolution';
+export { AliasImportDeclaration, isAliasImportDeclaration, loadIsReferencedAliasDeclarationPatch } from './src/patch_alias_reference_resolution';
 export { Reexport } from './src/reexport';
 export { OwningModule, Reference } from './src/references';
 export { ModuleResolver } from './src/resolver';

package/src/ngtsc/imports/src/core.d.ts

@@ -9,13 +9,6 @@
  * Rewrites imports of symbols being written into generated code.
  */
 export interface ImportRewriter {
-    /**
-     * Should the given symbol be imported at all?
-     *
-     * If `true`, the symbol should be imported from the given specifier. If `false`, the symbol
-     * should be referenced directly, without an import.
-     */
-    shouldImportSymbol(symbol: string, specifier: string): boolean;
     /**
      * Optionally rewrite a reference to an imported symbol, changing either the binding prefix or the
      * symbol name itself.
@@ -30,7 +23,6 @@ export interface ImportRewriter {
  * `ImportRewriter` that does no rewriting.
  */
 export declare class NoopImportRewriter implements ImportRewriter {
-    shouldImportSymbol(symbol: string, specifier: string): boolean;
     rewriteSymbol(symbol: string, specifier: string): string;
     rewriteSpecifier(specifier: string, inContextOfFile: string): string;
 }
@@ -41,7 +33,6 @@ export declare class NoopImportRewriter implements ImportRewriter {
 export declare class R3SymbolsImportRewriter implements ImportRewriter {
     private r3SymbolsPath;
     constructor(r3SymbolsPath: string);
-    shouldImportSymbol(symbol: string, specifier: string): boolean;
     rewriteSymbol(symbol: string, specifier: string): string;
     rewriteSpecifier(specifier: string, inContextOfFile: string): string;
 }

package/src/ngtsc/imports/src/patch_alias_reference_resolution.d.ts

@@ -6,6 +6,8 @@
  * found in the LICENSE file at https://angular.io/license
  */
 import ts from 'typescript';
+/** Possible alias import declarations */
+export type AliasImportDeclaration = ts.ImportSpecifier | ts.NamespaceImport | ts.ImportClause;
 /**
  * Patches the alias declaration reference resolution for a given transformation context
  * so that TypeScript knows about the specified alias declarations being referenced.
@@ -58,4 +60,4 @@ export declare function loadIsReferencedAliasDeclarationPatch(context: ts.Transf
  * declarations can be import specifiers, namespace imports or import clauses
  * as these do not declare an actual symbol but just point to a target declaration.
  */
-export declare function isAliasImportDeclaration(node: ts.Node): node is ts.ImportSpecifier | ts.NamespaceImport | ts.ImportClause;
+export declare function isAliasImportDeclaration(node: ts.Node): node is AliasImportDeclaration;

package/src/ngtsc/reflection/src/host.d.ts

@@ -77,6 +77,14 @@ export declare enum ClassMemberKind {
     Property = 3,
     Method = 4
 }
+/** Possible access levels of a class member. */
+export declare enum ClassMemberAccessLevel {
+    PublicWritable = 0,
+    PublicReadonly = 1,
+    Protected = 2,
+    Private = 3,
+    EcmaScriptPrivate = 4
+}
 /**
  * A member of a class, such as a property, method, or constructor.
  */
@@ -89,6 +97,8 @@ export interface ClassMember {
      * Indication of which type of member this is (property, method, etc).
      */
     kind: ClassMemberKind;
+    /** Access level describing the class member modifiers. */
+    accessLevel: ClassMemberAccessLevel;
     /**
      * TypeScript `ts.TypeNode` representing the type of the member, or `null` if not present or
      * applicable.
@@ -99,13 +109,13 @@ export interface ClassMember {
      */
     name: string;
     /**
-     * TypeScript `ts.Identifier` or `ts.StringLiteral` representing the name of the member, or `null`
-     * if no such node is present.
+     * TypeScript `ts.Identifier`, `ts.PrivateIdentifier`, or `ts.StringLiteral` representing the
+     * name of the member, or `null` if no such node is present.
      *
      * The `nameNode` is useful in writing references to this member that will be correctly source-
      * mapped back to the original file.
      */
-    nameNode: ts.Identifier | ts.StringLiteral | null;
+    nameNode: ts.Identifier | ts.PrivateIdentifier | ts.StringLiteral | null;
     /**
      * TypeScript `ts.Expression` which represents the value of the member.
      *

package/src/ngtsc/reflection/src/typescript.d.ts

@@ -52,7 +52,6 @@ export declare class TypeScriptReflectionHost implements ReflectionHost {
      */
     protected getDeclarationOfSymbol(symbol: ts.Symbol, originalId: ts.Identifier | null): Declaration | null;
     private _reflectDecorator;
-    private _reflectMember;
     /**
      * Get the set of declarations declared in `file` which are exported.
      */
@@ -69,6 +68,14 @@ export declare function filterToMembersWithDecorator(members: ClassMember[], nam
     member: ClassMember;
     decorators: Decorator[];
 }[];
+/**
+ * Reflects a class element and returns static information about the
+ * class member.
+ *
+ * Note: Decorator information is not included in this helper as it relies
+ * on type checking to resolve originating import.
+ */
+export declare function reflectClassMember(node: ts.ClassElement): Omit<ClassMember, 'decorators'> | null;
 export declare function findMember(members: ClassMember[], name: string, isStatic?: boolean): ClassMember | null;
 export declare function reflectObjectLiteral(node: ts.ObjectLiteralExpression): Map<string, ts.Expression>;
 /**

package/src/ngtsc/reflection/src/util.d.ts

@@ -6,7 +6,12 @@
  * found in the LICENSE file at https://angular.io/license
  */
 import ts from 'typescript';
-import { ClassDeclaration } from './host';
+import { ClassDeclaration, ClassMemberAccessLevel } from './host';
 export declare function isNamedClassDeclaration(node: ts.Node): node is ClassDeclaration<ts.ClassDeclaration>;
 export declare function isNamedFunctionDeclaration(node: ts.Node): node is ClassDeclaration<ts.FunctionDeclaration>;
 export declare function isNamedVariableDeclaration(node: ts.Node): node is ClassDeclaration<ts.VariableDeclaration>;
+/**
+ * Converts the given class member access level to a string.
+ * Useful fo error messages.
+ */
+export declare function classMemberAccessLevelToString(level: ClassMemberAccessLevel): string;

package/src/ngtsc/transform/index.d.ts

@@ -11,4 +11,3 @@ export { ClassRecord, TraitCompiler } from './src/compilation';
 export { declarationTransformFactory, DtsTransformRegistry, IvyDeclarationDtsTransform } from './src/declaration';
 export { AnalyzedTrait, PendingTrait, ResolvedTrait, SkippedTrait, Trait, TraitState } from './src/trait';
 export { ivyTransformFactory } from './src/transform';
-export { addImports } from './src/utils';

package/src/ngtsc/transform/src/declaration.d.ts

@@ -24,7 +24,7 @@ export declare class DtsTransformRegistry {
      */
     getAllTransforms(sf: ts.SourceFile): DtsTransform[] | null;
 }
-export declare function declarationTransformFactory(transformRegistry: DtsTransformRegistry, reflector: ReflectionHost, refEmitter: ReferenceEmitter, importRewriter: ImportRewriter, importPrefix?: string): ts.TransformerFactory<ts.SourceFile>;
+export declare function declarationTransformFactory(transformRegistry: DtsTransformRegistry, reflector: ReflectionHost, refEmitter: ReferenceEmitter, importRewriter: ImportRewriter): ts.TransformerFactory<ts.SourceFile>;
 export interface IvyDeclarationField {
     name: string;
     type: Type;

package/src/ngtsc/translator/index.d.ts

@@ -6,9 +6,9 @@
  * found in the LICENSE file at https://angular.io/license
  */
 export { AstFactory, BinaryOperator, LeadingComment, ObjectLiteralProperty, SourceMapLocation, SourceMapRange, TemplateElement, TemplateLiteral, UnaryOperator, VariableDeclarationType } from './src/api/ast_factory';
-export { ImportGenerator, NamedImport } from './src/api/import_generator';
+export { ImportGenerator, ImportRequest } from './src/api/import_generator';
 export { Context } from './src/context';
-export { Import, ImportManager, NamespaceImport, SideEffectImport } from './src/import_manager';
+export { ImportManager, ImportManagerConfig, presetImportManagerForceNamespaceImports } from './src/import_manager/import_manager';
 export { ExpressionTranslatorVisitor, RecordWrappedNodeFn, TranslatorOptions } from './src/translator';
 export { canEmitType, TypeEmitter, TypeReferenceTranslator } from './src/type_emitter';
 export { translateType } from './src/type_translator';

package/src/ngtsc/translator/src/api/import_generator.d.ts

@@ -6,14 +6,27 @@
  * found in the LICENSE file at https://angular.io/license
  */
 /**
- * The symbol name and import namespace of an imported symbol,
- * which has been registered through the ImportGenerator.
+ * A request to import a given symbol from the given module.
  */
-export interface NamedImport<TExpression> {
-    /** The import namespace containing this imported symbol. */
-    moduleImport: TExpression | null;
-    /** The (possibly rewritten) name of the imported symbol. */
-    symbol: string;
+export interface ImportRequest<TFile> {
+    /**
+     * Name of the export to be imported.
+     * May be `null` if a namespace import is requested.
+     */
+    exportSymbolName: string | null;
+    /**
+     * Module specifier to be imported.
+     * May be a module name, or a file-relative path.
+     */
+    exportModuleSpecifier: string;
+    /**
+     * File for which the import is requested for. This may
+     * be used by import generators to re-use existing imports.
+     *
+     * Import managers may also allow this to be nullable if
+     * imports are never re-used. E.g. in the linker generator.
+     */
+    requestedFile: TFile;
 }
 /**
  * Generate import information based on the context of the code being generated.
@@ -21,7 +34,6 @@ export interface NamedImport<TExpression> {
  * Implementations of these methods return a specific identifier that corresponds to the imported
  * module.
  */
-export interface ImportGenerator<TExpression> {
-    generateNamespaceImport(moduleName: string): TExpression;
-    generateNamedImport(moduleName: string, originalSymbol: string): NamedImport<TExpression>;
+export interface ImportGenerator<TFile, TExpression> {
+    addImport(request: ImportRequest<TFile>): TExpression;
 }

package/src/ngtsc/translator/src/import_manager/check_unique_identifier_name.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import type { ImportManagerConfig } from './import_manager';
+/**
+ * Generates a helper for `ImportManagerConfig` to generate unique identifiers
+ * for a given source file.
+ */
+export declare function createGenerateUniqueIdentifierHelper(): ImportManagerConfig['generateUniqueIdentifier'];

package/src/ngtsc/translator/src/import_manager/import_manager.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import ts from 'typescript';
+import { AliasImportDeclaration, ImportRewriter } from '../../../imports';
+import { ImportGenerator, ImportRequest } from '../api/import_generator';
+/** Configuration for the import manager. */
+export interface ImportManagerConfig {
+    generateUniqueIdentifier(file: ts.SourceFile, baseName: string): ts.Identifier | null;
+    shouldUseSingleQuotes(file: ts.SourceFile): boolean;
+    rewriter: ImportRewriter | null;
+    namespaceImportPrefix: string;
+    disableOriginalSourceFileReuse: boolean;
+    forceGenerateNamespacesForNewImports: boolean;
+}
+/**
+ * Preset configuration for forcing namespace imports.
+ *
+ * This preset is commonly used to avoid test differences to previous
+ * versions of the `ImportManager`.
+ */
+export declare const presetImportManagerForceNamespaceImports: Partial<ImportManagerConfig>;
+/** Branded string to identify a module name. */
+export type ModuleName = string & {
+    __moduleName: boolean;
+};
+/**
+ * Import manager that can be used to conveniently and efficiently generate
+ * imports It efficiently re-uses existing source file imports, or previous
+ * generated imports.
+ *
+ * These capabilities are important for efficient TypeScript transforms that
+ * minimize structural changes to the dependency graph of source files, enabling
+ * as much incremental re-use as possible.
+ *
+ * Those imports may be inserted via a TypeScript transform, or via manual string
+ * manipulation using e.g. `magic-string`.
+ */
+export declare class ImportManager implements ImportGenerator<ts.SourceFile, ts.Identifier | ts.PropertyAccessExpression> {
+    private _config;
+    /** List of new imports that will be inserted into given source files. */
+    private newImports;
+    private nextUniqueIndex;
+    private config;
+    private reuseSourceFileImportsTracker;
+    private reuseGeneratedImportsTracker;
+    constructor(_config?: Partial<ImportManagerConfig>);
+    /** Adds a side-effect import for the given module. */
+    addSideEffectImport(requestedFile: ts.SourceFile, moduleSpecifier: string): void;
+    /**
+     * Adds an import to the given source-file and returns a TypeScript
+     * expression that can be used to access the newly imported symbol.
+     */
+    addImport(request: ImportRequest<ts.SourceFile> & {
+        asTypeReference: true;
+    }): ts.Identifier | ts.QualifiedName;
+    addImport(request: ImportRequest<ts.SourceFile> & {
+        asTypeReference?: undefined;
+    }): ts.Identifier | ts.PropertyAccessExpression;
+    private _generateNewImport;
+    /**
+     * Finalizes the import manager by computing all necessary import changes
+     * and returning them.
+     *
+     * Changes are collected once at the end, after all imports are requested,
+     * because this simplifies building up changes to existing imports that need
+     * to be updated, and allows more trivial re-use of previous generated imports.
+     */
+    finalize(): {
+        affectedFiles: Set<string>;
+        updatedImports: Map<ts.NamedImports, ts.NamedImports>;
+        newImports: Map<string, ts.ImportDeclaration[]>;
+        reusedOriginalAliasDeclarations: Set<AliasImportDeclaration>;
+    };
+    /**
+     * Gets a TypeScript transform for the import manager.
+     *
+     * @param extraStatementsMap Additional set of statements to be inserted
+     *   for given source files after their imports. E.g. top-level constants.
+     */
+    toTsTransform(extraStatementsMap?: Map<string, ts.Statement[]>): ts.TransformerFactory<ts.SourceFile>;
+    /**
+     * Transforms a single file as a shorthand, using {@link toTsTransform}.
+     *
+     * @param extraStatementsMap Additional set of statements to be inserted
+     *   for given source files after their imports. E.g. top-level constants.
+     */
+    transformTsFile(ctx: ts.TransformationContext, file: ts.SourceFile, extraStatementsAfterImports?: ts.Statement[]): ts.SourceFile;
+    private _getNewImportsTrackerForFile;
+}

package/src/ngtsc/translator/src/import_manager/import_typescript_transform.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import ts from 'typescript';
+import type { ImportManager } from './import_manager';
+/**
+ * Creates a TypeScript transform for the given import manager.
+ *
+ *  - The transform updates existing imports with new symbols to be added.
+ *  - The transform adds new necessary imports.
+ *  - The transform inserts additional optional statements after imports.
+ */
+export declare function createTsTransformForImportManager(manager: ImportManager, extraStatementsForFiles?: Map<string, ts.Statement[]>): ts.TransformerFactory<ts.SourceFile>;