session.test|title=sessionFileChangesEqual returns false when one entry is v1 and the other is v2|occurrence=1

1 > /*--------------------------------------------------------------------------------------------- chatSessionsService.ts

2 > * Copyright (c) Microsoft Corporation. All rights reserved.

3 > * Licensed under the MIT License. See License.txt in the project root for license information.

4 > *--------------------------------------------------------------------------------------------*/

5 >

6 > import { CancellationToken } from '../../../../base/common/cancellation.js';

7 > import { Event } from '../../../../base/common/event.js';

8 > import { IMarkdownString } from '../../../../base/common/htmlContent.js';

9 > import { IDisposable } from '../../../../base/common/lifecycle.js';

10 > import { IObservable } from '../../../../base/common/observable.js';

11 > import { ThemeIcon } from '../../../../base/common/themables.js';

12 > import { URI } from '../../../../base/common/uri.js';

13 > import { IPosition } from '../../../../editor/common/core/position.js';

14 > import { isRemoteAgentHostSessionType } from '../../../../platform/agentHost/common/agentHostSessionType.js';

15 > import { createDecorator, ServicesAccessor } from '../../../../platform/instantiation/common/instantiation.js';

16 > import { Registry } from '../../../../platform/registry/common/platform.js';

17 > import { LOCAL_AGENT_HOST_SCHEME_PREFIX } from '../../../../platform/agentHost/common/agentHostConnectionsService.js';

18 > import { IChatAgentAttachmentCapabilities, IChatAgentRequest } from './participants/chatAgents.js';

19 > import { IChatEditingSession } from './editing/chatEditingService.js';

20 > import { IChatRequestModeInstructions, IChatRequestVariableData, ISerializableChatModelInputState } from './model/chatModel.js';

21 > import { IChatProgress, IChatResponseErrorDetails, IChatSessionTiming } from './chatService/chatService.js';

22 > import { Target } from './promptSyntax/promptTypes.js';

23 >

24 > export const enum ChatSessionsExtensions {

25 > AsyncActivation = 'workbench.contrib.chatSessions.asyncActivation'

26 > }

27 >

28 > export interface IAsyncChatSessionActivationContribution {

29 > matchSessionType(sessionType: string): boolean;

30 > waitForActivation(accessor: ServicesAccessor, sessionType: string): Promise<boolean>;

31 > }

32 >

33 > export interface IAsyncChatSessionActivationRegistry {

34 > register(contribution: IAsyncChatSessionActivationContribution): IDisposable;

35 > getActivators(sessionType: string): readonly IAsyncChatSessionActivationContribution[];

36 > }

37 >

38 > class AsyncChatSessionActivationRegistry implements IAsyncChatSessionActivationRegistry {

39 > private readonly _contributions = new Set<IAsyncChatSessionActivationContribution>();

40 >

41 > register(contribution: IAsyncChatSessionActivationContribution): IDisposable {

42 this._contributions.add(contribution);

43 return {

45 };

46 }

47 > chatSessionsService.ts

48 > getActivators(sessionType: string): readonly IAsyncChatSessionActivationContribution[] {

49 return Array.from(this._contributions).filter(contribution => contribution.matchSessionType(sessionType));

50 }

51 > } chatSessionsService.ts

52 >

53 > Registry.add(ChatSessionsExtensions.AsyncActivation, new AsyncChatSessionActivationRegistry());

54 >

55 > export const enum ChatSessionStatus {

56 > Failed = 0,

57 > Completed = 1,

58 > InProgress = 2,

59 > NeedsInput = 3

60 > }

61 >

62 > export interface IChatSessionCommandContribution {

63 > readonly name: string;

64 > readonly description: string;

65 > readonly when?: string;

66 > }

67 >

68 > export interface IChatSessionProviderOptionModelMetadata {

69 > readonly name: string;

70 > readonly id: string;

71 > readonly vendor?: string;

72 > readonly version?: string;

73 > readonly family?: string;

74 > readonly tooltip?: string;

75 > readonly pricing?: string;

76 > readonly multiplierNumeric?: number;

77 > readonly inputCost?: number;

78 > readonly outputCost?: number;

79 > readonly cacheCost?: number;

80 > readonly cacheWriteCost?: number;

81 > readonly longContextInputCost?: number;

82 > readonly longContextOutputCost?: number;

83 > readonly longContextCacheCost?: number;

84 > readonly longContextCacheWriteCost?: number;

85 > readonly priceCategory?: string;

86 > readonly promo?: {

87 > readonly id: string;

88 > readonly discountPercent: number;

89 > readonly endsAt: string;

90 > readonly message: string;

91 > };

92 > readonly maxInputTokens?: number;

93 > readonly maxOutputTokens?: number;

94 > readonly capabilities?: {

95 > readonly vision?: boolean;

96 > readonly toolCalling?: boolean;

97 > };

98 > }

99 >

100 > export interface IChatSessionProviderOptionItem {

101 > readonly id: string;

102 > readonly name: string;

103 > readonly description?: string;

104 > readonly detail?: string;

105 > readonly locked?: boolean;

106 > readonly icon?: ThemeIcon;

107 > readonly default?: boolean;

108 > readonly slashCommand?: string;

109 > readonly tooltip?: string;

110 > readonly modelMetadata?: IChatSessionProviderOptionModelMetadata;

111 > // [key: string]: any;

112 > }

113 >

114 > export interface IChatSessionProviderOptionGroupCommand {

115 > readonly command: string;

116 > readonly title: string;

117 > readonly tooltip?: string;

118 > readonly arguments?: readonly unknown[];

119 > }

120 >

121 > export interface IChatSessionProviderOptionGroup {

122 > readonly id: string;

123 > readonly name: string;

124 > readonly description?: string;

125 > readonly detail?: string;

126 > readonly selected?: IChatSessionProviderOptionItem;

127 > readonly items: readonly IChatSessionProviderOptionItem[];

128 > /**

129 > * A context key expression that controls visibility of this option group picker.

130 > * When specified, the picker is only visible when the expression evaluates to true.

131 > * The expression can reference other option group values via `chatSessionOption.<groupId>`.

132 > * Example: `"chatSessionOption.models == 'gpt-4'"`

133 > */

134 > readonly when?: string;

135 > readonly icon?: ThemeIcon;

136 > /**

137 > * Custom commands to show in the option group's picker UI.

138 > * These will be shown in a separate section at the end of the picker.

139 > */

140 > readonly commands?: readonly IChatSessionProviderOptionGroupCommand[];

141 > /**

142 > * Optional kind hint that controls how the group is presented.

143 > * - `'permissions'`: the group's items are surfaced inside the chat permission picker

144 > * instead of being rendered as a standalone picker. At most one group per provider

145 > * may use this kind; if multiple are declared, the first one (in declaration order)

146 > * wins. The group has no UI of its own — it is invisible when the permission

147 > * picker is hidden by its own `when` clauses.

148 > */

149 > readonly kind?: 'permissions';

150 > }

151 >

152 > export interface IChatSessionsExtensionPoint {

153 > readonly type: string;

154 > readonly name: string;

155 > readonly displayName: string;

156 > readonly description: string;

157 > readonly when?: string;

158 > readonly icon?: string | { light: string; dark: string };

159 > readonly order?: number;

160 > readonly alternativeIds?: string[];

161 > readonly welcomeTitle?: string;

162 > readonly welcomeMessage?: string;

163 > readonly welcomeTips?: string;

164 > readonly inputPlaceholder?: string;

165 > readonly capabilities?: IChatAgentAttachmentCapabilities;

166 > readonly commands?: IChatSessionCommandContribution[];

167 > readonly canDelegate?: boolean;

168 > readonly isReadOnly?: boolean;

169 > /**

170 > * When set, the chat session will show a filtered mode picker with custom agents

171 > * that have a matching `target` property. This enables contributed chat sessions

172 > * to reuse the standard agent/mode dropdown with filtered custom agents.

173 > * Custom agents without a `target` property are also shown in all filtered lists

174 > */

175 > readonly customAgentTarget?: Target;

176 > readonly requiresCustomModels?: boolean;

177 > /**

178 > * Whether this session type supports the synthetic "Auto" model fallback.

179 > * Defaults to true. When false and no models are available, the picker

180 > * shows a "No models available" state instead of "Auto".

181 > *

182 > * This is distinct from {@link requiresCustomModels}, which only controls

183 > * whether the picker is filtered to the session's own model pool — a

184 > * session can own a custom pool yet still support Auto (e.g. the Copilot

185 > * CLI agent host).

186 > */

187 > readonly supportsAutoModel?: boolean;

188 > /**

189 > * Logical Agent Host provider ID for Agent Host-backed chat sessions.

190 > * For example, both local `agent-host-copilotcli` and remote

191 > * `remote-{authority}-copilotcli` sessions use `copilotcli`.

192 > */

193 > readonly agentHostProviderId?: string;

194 > /**

195 > * Whether this type needs a GitHub Copilot account and so is unusable until the user signs in. Set by

196 > * Copilot-backed types (Copilot CLI / agent host, cloud agent) where BYOK isn't supported. Defaults to false, so

197 > * third-party types that don't depend on Copilot stay usable while signed out.

198 > */

199 > readonly requiresCopilotSignIn?: boolean;

200 > /**

201 > * When false, the delegation picker is hidden for this session type.

202 > * Defaults to true.

203 > */

204 > readonly supportsDelegation?: boolean;

205 > /**

206 > * Decides whether to automatically attach instruction files to chat requests

207 > * for this session type. Defaults to false when not specified.

208 > */

209 > readonly autoAttachReferences?: boolean;

210 > }

211 >

212 > export interface IChatSessionItem {

213 > readonly resource: URI;

214 > readonly label: string;

215 > readonly iconPath?: ThemeIcon;

216 > readonly badge?: string | IMarkdownString;

217 > readonly description?: string | IMarkdownString;

218 > readonly status?: ChatSessionStatus;

219 > readonly tooltip?: string | IMarkdownString;

220 > readonly timing: IChatSessionTiming;

221 > readonly changes?: {

222 > readonly files: number;

223 > readonly insertions: number;

224 > readonly deletions: number;

225 > } | readonly IChatSessionFileChange[] | readonly IChatSessionFileChange2[];

226 > readonly archived?: boolean;

227 > readonly metadata?: IChatSessionItemMetadata;

228 > /**

229 > * Resource identifier the item was previously known by. When set, host-stored

230 > * per-resource state (archive, pin, read) recorded under that URI is adopted

231 > * forward onto {@link resource} on first state read, and the legacy entry is

232 > * removed. Scheme must match {@link resource}'s scheme; otherwise ignored.

233 > */

234 > readonly legacyResource?: URI;

235 > }

236 >

237 > export interface IChatSessionItemMetadata {

238 > //#region Changes metadata (for sessions window)

239 > readonly repositoryPath?: string;

240 > readonly workingDirectoryPath?: string;

241 > readonly firstCheckpointRef?: string;

242 > readonly lastCheckpointRef?: string;

243 > readonly worktreePath?: string;

244 > readonly uncommittedChanges?: number;

245 > readonly baseRefOid?: string;

246 > readonly headRefOid?: string;

247 > readonly branchName?: string;

248 > readonly branch?: string;

249 > readonly baseBranchName?: string;

250 > readonly baseBranch?: string;

251 > readonly baseBranchProtected?: boolean;

252 > readonly hasGitHubRemote?: boolean;

253 > readonly upstreamBranchName?: string;

254 > readonly incomingChanges?: number;

255 > readonly outgoingChanges?: number;

256 > //#endregion

257 >

258 > readonly [key: string]: unknown;

259 > }

260 >

261 > export interface IChatSessionFileChange {

262 > readonly modifiedUri: URI;

263 > readonly originalUri?: URI;

264 > readonly insertions: number;

265 > readonly deletions: number;

266 > readonly reviewed?: boolean;

267 > }

268 >

269 > export interface IChatSessionFileChange2 {

270 > readonly uri: URI;

271 > readonly originalUri?: URI;

272 > readonly modifiedUri?: URI;

273 > readonly insertions: number;

274 > readonly deletions: number;

275 > readonly reviewed?: boolean;

276 > }

277 >

278 > export type IChatSessionHistoryItem = {

279 > id?: string;

280 > type: 'request';

281 > prompt: string;

282 > participant: string;

283 > command?: string;

284 > variableData?: IChatRequestVariableData;

285 > modelId?: string;

286 > timestamp?: number;

287 > modeInstructions?: IChatRequestModeInstructions;

288 > isSystemInitiated?: boolean;

289 > systemInitiatedLabel?: string;

290 > isTerminalRequest?: boolean;

291 > } | {

292 > type: 'response';

293 > parts: IChatProgress[];

294 > participant: string;

295 > details?: string;

296 > elapsedMs?: number;

297 > completedAt?: number;

298 > /**

299 > * Error details for a failed response. Rendered as a proper chat error

300 > * (including the quota-exceeded upgrade affordance), mirroring the live

301 > * agent result's `errorDetails`.

302 > */

303 > errorDetails?: IChatResponseErrorDetails;

304 > };

305 >

306 > export type IChatSessionRequestHistoryItem = Extract<IChatSessionHistoryItem, { type: 'request' }>;

307 >

308 > export interface IChatSessionServerRequest {

309 > readonly prompt: string;

310 > readonly variableData?: IChatRequestVariableData;

311 > readonly timestamp?: number;

312 > readonly isSystemInitiated?: boolean;

313 > readonly systemInitiatedLabel?: string;

314 > readonly isTerminalRequest?: boolean;

315 > }

316 >

317 > /**

318 > * Whether `text` runs as a terminal command for the given command `prefix`

319 > * (e.g. `!`) — it starts with the prefix and has a non-empty command after it.

320 > * Mirrors the agent host's bang parser, where a lone `!` (or `!` followed only

321 > * by whitespace) is forwarded to the agent rather than executed.

322 > */

323 > export function isTerminalCommandPrompt(text: string, prefix: string | undefined): boolean {

324 return !!prefix && text.startsWith(prefix) && text.slice(prefix.length).trim().length > 0;

325 }

326 > chatSessionsService.ts

327 > /**

328 > * A set of well-known session types

329 > */

330 > export namespace SessionType {

331 > export const CopilotCLI = 'copilotcli';

332 > export const CopilotCloud = 'copilot-cloud-agent';

333 > export const Local = 'local';

334 > export const ClaudeCode = 'claude-code';

335 > export const Codex = 'openai-codex';

336 > export const Growth = 'copilot-growth';

337 > export const AgentHostCopilot = 'agent-host-copilotcli';

338 > export const AgentHostClaude = 'agent-host-claude';

339 > export const AgentHostCodex = 'agent-host-codex';

340 > }

341 >

342 > /**

343 > * Returns whether the given session type is a local agent host target.

344 > */

345 > export function isLocalAgentHostTarget(target: string): boolean {

346 return target === SessionType.AgentHostCopilot ||

347 target.startsWith(LOCAL_AGENT_HOST_SCHEME_PREFIX);

348 }

349 > chatSessionsService.ts

350 > /**

351 > * Returns whether the given session type is a remote agent host target.

352 > *

353 > * Note: The `remote-` prefix convention is established by

354 > * `RemoteAgentHostContribution` which generates session types as

355 > * `remote-{sanitizedAddress}-{provider}`. If future remote providers that

356 > * are NOT agent hosts need a different prefix, this function must be updated.

357 > */

358 > export function isRemoteAgentHostTarget(target: string): boolean {

359 return isRemoteAgentHostSessionType(target);

360 }

361 > chatSessionsService.ts

362 > /**

363 > * Returns whether the given session type is an agent host target.

364 > * Matches the local agent host (`agent-host-*`) and remote agent hosts (`remote-*`).

365 > */

366 > export function isAgentHostTarget(target: string): boolean {

367 return isLocalAgentHostTarget(target) || isRemoteAgentHostTarget(target);

368 }

369 > chatSessionsService.ts

370 > /**

371 > * The session type used for local agent chat sessions.

372 > */

373 > export const localChatSessionType = SessionType.Local;

374 >

375 > export interface IChatSession extends IDisposable {

376 > readonly onWillDispose: Event<void>;

377 >

378 > readonly sessionResource: URI;

379 >

380 > readonly title?: string;

381 >

382 > readonly history: readonly IChatSessionHistoryItem[];

383 >

384 >

385 > readonly options?: ReadonlyChatSessionOptionsMap;

386 >

387 > readonly progressObs?: IObservable<IChatProgress[]>;

388 > readonly isCompleteObs?: IObservable<boolean>;

389 > readonly isReadOnly?: IObservable<boolean>;

390 > readonly interruptActiveResponseCallback?: () => Promise<boolean>;

391 >

392 > /**

393 > * Event fired when the server initiates a new request (e.g. from a consumed

394 > * queued message). The consumer should create a new request+response pair in

395 > * the model and prepare to receive progress via {@link progressObs}.

396 > */

397 > readonly onDidStartServerRequest?: Event<IChatSessionServerRequest>;

398 >

399 > /**

400 > * Editing session transferred from a previously-untitled chat session in `onDidCommitChatSessionItem`.

401 > */

402 > transferredState?: {

403 > readonly editingSession: IChatEditingSession | undefined;

404 > readonly inputState: ISerializableChatModelInputState | undefined;

405 > };

406 >

407 > requestHandler?: (

408 > request: IChatAgentRequest,

409 > progress: (progress: IChatProgress[]) => void,

410 > // eslint-disable-next-line @typescript-eslint/no-explicit-any

411 > history: any[], // TODO: Nail down types

412 > token: CancellationToken

413 > ) => Promise<void>;

414 >

415 > /**

416 > * Forks the session from the given request point.

417 > * @param request The request history item to fork from, or undefined to fork from the end.

418 > * @param token Cancellation token.

419 > * @returns The forked session item. The promise is rejected if forking fails.

420 > */

421 > forkSession?: (request: IChatSessionRequestHistoryItem | undefined, token: CancellationToken) => Promise<IChatSessionItem>;

422 >

423 > /**

424 > * Renames the session.

425 > * @param title The new title for the session.

426 > * @param token Cancellation token.

427 > * @returns A promise that resolves once the rename has been dispatched. The promise is rejected if renaming fails.

428 > */

429 > renameSession?: (title: string, token: CancellationToken) => Promise<void>;

430 > }

431 >

432 > export interface IChatSessionContentProvider {

433 > provideChatSessionContent(sessionResource: URI, token: CancellationToken): Promise<IChatSession>;

434 >

435 > /** Resolves a parsed response Markdown URI before it is sanitized and rendered. */

436 > resolveChatResponseUri?(sessionResource: URI, href: string, kind: 'link' | 'image'): string;

437 >

438 > /**

439 > * Optional. Compute completion items for an input being composed in this

440 > * session. Returning `undefined` lets the workbench fall back to its

441 > * default in-process completion providers.

442 > */

443 > provideChatInputCompletions?(sessionResource: URI, params: IChatInputCompletionsParams, token: CancellationToken): Promise<IChatInputCompletionsResult | undefined>;

444 >

445 > /**

446 > * Optional. Trigger characters that, when typed in the chat input,

447 > * SHOULD cause the workbench to issue a `provideChatInputCompletions`

448 > * request. Used to register a Monaco completion provider scoped to

449 > * sessions handled by this content provider.

450 > */

451 > provideChatInputCompletionTriggerCharacters?(): Promise<readonly string[]>;

452 > }

453 >

454 > /**

455 > * Inputs for {@link IChatSessionContentProvider.provideChatInputCompletions}

456 > * and {@link IChatSessionsService.provideChatInputCompletions}.

457 > */

458 > export interface IChatInputCompletionsParams {

459 > /**

460 > * The complete text of the input being completed (e.g. the user message

461 > * the user is currently composing).

462 > */

463 > readonly text: string;

464 > /**

465 > * The character offset within {@link text} at which the completion is

466 > * requested, measured in UTF-16 code units. MUST satisfy

467 > * `0 <= offset <= text.length`.

468 > */

469 > readonly offset: number;

470 > }

471 >

472 > /**

473 > * A neutral completion-item shape returned by

474 > * {@link IChatSessionContentProvider.provideChatInputCompletions}. The

475 > * workbench-side completion glue maps these into Monaco completion items

476 > * and the corresponding chat-input attachment.

477 > */

478 > export interface IChatInputCompletionItem {

479 > /** Text inserted into the input when this item is accepted. */

480 > readonly insertText: string;

481 > /**

482 > * Optional display label shown in the completion picker. When omitted, the

483 > * workbench displays {@link insertText}. Set this when the inserted text

484 > * differs from the label — e.g. an action item that inserts nothing

485 > * (`insertText: ''`) but should still be shown to the user.

486 > */

487 > readonly label?: string;

488 > /**

489 > * Half-open range `[start, end)` in the *current* input text that

490 > * {@link insertText} replaces. Positions use 1-based `lineNumber` and

491 > * `column` to match Monaco. When omitted, the workbench replaces the

492 > * word at the cursor.

493 > */

494 > readonly start?: IPosition;

495 > readonly end?: IPosition;

496 > /** Attachment associated with the item. */

497 > readonly attachment: IChatInputCompletionResourceAttachment | IChatInputCompletionCommandAttachment | IChatInputCompletionSkillAttachment;

498 > }

499 >

500 > /**

501 > * Resource attachment associated with a completion item. The workbench

502 > * adds it to the input's variable model when the item is accepted.

503 > */

504 > export interface IChatInputCompletionResourceAttachment {

505 > readonly kind: 'resource';

506 > readonly uri: URI;

507 > readonly displayName?: string;

508 > readonly isDirectory?: boolean;

509 > /**

510 > * Implementation-defined metadata that MUST be preserved by the

511 > * workbench when the accepted completion is sent back as part of a

512 > * user message attachment.

513 > */

514 > readonly _meta?: Record<string, unknown>;

515 > }

516 >

517 > /**

518 > * Command attachment associated with a completion item.

519 > */

520 > export interface IChatInputCompletionCommandAttachment {

521 > readonly kind: 'command';

522 > readonly command: string;

523 > readonly description: string;

524 > /**

525 > * Implementation-defined metadata that MUST be preserved by the

526 > * workbench when the accepted completion is sent back as part of a

527 > * user message attachment.

528 > */

529 > readonly _meta?: Record<string, unknown>;

530 > }

531 >

532 > /**

533 > * Skill attachment associated with a completion item. The workbench

534 > * adds it to the input's variable model when the item is accepted.

535 > */

536 > export interface IChatInputCompletionSkillAttachment {

537 > readonly kind: 'skill';

538 > readonly uri: URI;

539 > readonly displayName?: string;

540 > readonly description?: string;

541 > /**

542 > * Implementation-defined metadata that MUST be preserved by the

543 > * workbench when the accepted completion is sent back as part of a

544 > * user message attachment.

545 > */

546 > readonly _meta?: Record<string, unknown>;

547 > }

548 >

549 > /**

550 > * Result of {@link IChatSessionContentProvider.provideChatInputCompletions}.

551 > */

552 > export interface IChatInputCompletionsResult {

553 > readonly items: readonly IChatInputCompletionItem[];

554 > }

555 >

556 > export interface IChatNewSessionRequest {

557 > readonly prompt: string;

558 > readonly command?: string;

559 >

560 > readonly initialSessionOptions?: ReadonlyChatSessionOptionsMap;

561 >

562 > /**

563 > * The chat-input session resource the user was typing into when this

564 > * request was issued. Set when the chat infrastructure is rewriting an

565 > * untitled session URI to a real one on first send. Controllers can use

566 > * this to bridge any pre-creation state they tracked under the old URI

567 > * (e.g. provisional agent-host sessions) to the new resource that the

568 > * controller returns.

569 > */

570 > readonly untitledResource?: URI;

571 > }

572 >

573 > export interface IChatSessionItemsDelta {

574 > readonly addedOrUpdated?: readonly IChatSessionItem[];

575 > readonly removed?: readonly URI[];

576 > }

577 >

578 > export interface IChatSessionItemController {

579 >

580 > readonly onDidChangeChatSessionItems: Event<IChatSessionItemsDelta>;

581 >

582 > get items(): readonly IChatSessionItem[];

583 >

584 > refresh(token: CancellationToken): Promise<void>;

585 >

586 > newChatSessionItem?(request: IChatNewSessionRequest, token: CancellationToken): Promise<IChatSessionItem | undefined>;

587 >

588 > getNewChatSessionInputState?(sessionResource: URI, token: CancellationToken): Promise<readonly IChatSessionProviderOptionGroup[] | undefined>;

589 >

590 > resolveChatSessionItem?(resource: URI, token: CancellationToken): Promise<IChatSessionItem | undefined>;

591 >

592 > /**

593 > * Permanently delete the session identified by `resource`. Implementations should tear down any backend state for

594 > * the session. The controller is expected to fire an `onDidChangeChatSessionItems` event with the removed resource

595 > * as a result of the deletion.

596 > */

597 > deleteChatSessionItem?(resource: URI, token: CancellationToken): Promise<void>;

598 >

599 > /**

600 > * Set the authoritative archived state for the session identified by `resource`.

601 > */

602 > setChatSessionItemArchived?(resource: URI, archived: boolean): void;

603 > }

604 >

605 > export interface IChatSessionOptionsChangeEvent {

606 > readonly sessionResource: URI;

607 > readonly updates: ReadonlyMap<string, string | IChatSessionProviderOptionItem | undefined>;

608 > }

609 >

610 > export type ResolvedChatSessionsExtensionPoint = Omit<IChatSessionsExtensionPoint, 'icon'> & {

611 > readonly icon: ThemeIcon | URI | undefined;

612 > };

613 >

614 > /**

615 > * Session options as key-value pairs.

616 > *

617 > * Keys correspond to option group IDs (e.g., 'models', 'subagents') and values are either the selected option item IDs (string) or full option items (for locked state).

618 > */

619 > export type ChatSessionOptionsMap = Map<string, string | IChatSessionProviderOptionItem>;

620 >

621 > export namespace ChatSessionOptionsMap {

622 > export function fromRecord(obj: { [key: string]: string | IChatSessionProviderOptionItem }): ChatSessionOptionsMap {

623 return new Map(Object.entries(obj));

624 }

625 > chatSessionsService.ts

626 > export function toRecord(map: ReadonlyChatSessionOptionsMap): Record<string, string | IChatSessionProviderOptionItem> {

627 const record: Record<string, string | IChatSessionProviderOptionItem> = Object.create(null);

628 const entries = ensureIterable(map);

632 return record;

633 }

634 > chatSessionsService.ts

635 > export function toStrValueArray(map: ReadonlyChatSessionOptionsMap | undefined): Array<{ optionId: string; value: string }> | undefined {

636 if (!map) {

637 return undefined;

640 return Array.from(entries, ([optionId, value]) => ({ optionId, value: typeof value === 'string' ? value : value.id }));

641 }

642 > chatSessionsService.ts

643 > /**

644 > * Ensures the input is iterable. If a plain object is passed (e.g. due to

645 > * serialization across process boundaries losing the Map prototype), it is

646 > * converted to Map entries on the fly.

647 > */

648 > function ensureIterable(map: ReadonlyChatSessionOptionsMap): Iterable<[string, string | IChatSessionProviderOptionItem]> {

649 if (map instanceof Map) {

650 return map;

653 return Object.entries(map as unknown as Record<string, string | IChatSessionProviderOptionItem>);

654 }

655 > } chatSessionsService.ts

656 >

657 > /**

658 > * Readonly version of {@link ChatSessionOptionsMap}

659 > */

660 > export type ReadonlyChatSessionOptionsMap = ReadonlyMap<string, string | IChatSessionProviderOptionItem>;

661 >

662 > export interface IChatSessionCustomizationItem {

663 > readonly label: string;

664 > readonly description?: string;

665 > readonly uri: URI;

666 > readonly storageLocation: number;

667 > readonly icon?: ThemeIcon;

668 > }

669 >

670 > export interface IChatSessionCustomizationItemGroup {

671 > readonly id: string;

672 > readonly items: IChatSessionCustomizationItem[];

673 > readonly commands?: readonly { readonly id: string; readonly title: string; readonly arguments?: readonly unknown[] }[];

674 > readonly itemCommands?: readonly { readonly id: string; readonly title: string; readonly arguments?: readonly unknown[] }[];

675 > }

676 >

677 > export interface IChatSessionCustomizationsProvider {

678 > readonly onDidChangeCustomizations: Event<void>;

679 > provideCustomizations(token: CancellationToken): Promise<IChatSessionCustomizationItemGroup[] | undefined>;

680 > }

681 >

682 >

683 > export interface IChatSessionCommitEvent {

684 > /** The original (untitled) session resource. */

685 > readonly original: URI;

686 > /** The committed (real) session resource. */

687 > readonly committed: URI;

688 > }

689 >

690 > export const IChatSessionsService = createDecorator<IChatSessionsService>('chatSessionsService');

691 >

692 > export interface IChatSessionsService {

693 > readonly _serviceBrand: undefined;

694 >

695 > // #region Chat session item provider support

696 > readonly onDidChangeItemsProviders: Event<{ readonly chatSessionType: string }>;

697 > readonly onDidChangeSessionItems: Event<IChatSessionItemsDelta>;

698 >

699 > /**

700 > * Fired when an untitled session is committed (URI swapped to a real resource)

701 > * after the first turn completes.

702 > */

703 > readonly onDidCommitSession: Event<IChatSessionCommitEvent>;

704 >

705 > readonly onDidChangeAvailability: Event<void>;

706 > readonly onDidChangeInProgress: Event<void>;

707 >

708 > getChatSessionContribution(chatSessionType: string): ResolvedChatSessionsExtensionPoint | undefined;

709 > getAllChatSessionContributions(): ResolvedChatSessionsExtensionPoint[];

710 >

711 > /**

712 > * Programmatically register a chat session contribution (for internal session types

713 > * that don't go through the extension point).

714 > */

715 > registerChatSessionContribution(contribution: IChatSessionsExtensionPoint): IDisposable;

716 >

717 > registerChatSessionItemController(chatSessionType: string, controller: IChatSessionItemController): IDisposable;

718 > getRegisteredChatSessionItemProviders(): readonly string[];

719 > activateChatSessionItemProvider(chatSessionType: string): Promise<void>;

720 >

721 > /**

722 > * Get the list of current chat session items grouped by session type.

723 > *

724 > * @param providerTypeFilter If specified, only returns items from the given providers. If undefined, returns items from all providers.

725 > *

726 > * @returns An async iterable that produces the list of session items for each provider. The order is not guaranteed. Some provider may take a long time to resolve.

727 > */

728 > getChatSessionItems(providerTypeFilter: readonly string[] | undefined, token: CancellationToken): AsyncIterable<{ readonly chatSessionType: string; readonly items: readonly IChatSessionItem[] }>;

729 >

730 > /**

731 > * Forces the controllers to refresh their session items, optionally filtered by provider type.

732 > */

733 > refreshChatSessionItems(providerTypeFilter: readonly string[] | undefined, token: CancellationToken): Promise<void>;

734 >

735 > /** @deprecated Use `getChatSessionItems` */

736 > getInProgress(): { chatSessionType: string; count: number }[];

737 >

738 > /**

739 > * Lazily resolves a chat session item, filling in expensive details like timing, changes, and badge.

740 > * Returns the resolved item, or undefined if no resolve handler is available.

741 > */

742 > resolveChatSessionItem(chatSessionType: string, resource: URI, token: CancellationToken): Promise<IChatSessionItem | undefined>;

743 >

744 > /**

745 > * Whether the registered item controller owns archived state for the session.

746 > */

747 > canSetChatSessionItemArchived(sessionResource: URI): boolean;

748 >

749 > /**

750 > * Sets archived state by delegating to the registered item controller.

751 > */

752 > setChatSessionItemArchived(sessionResource: URI, archived: boolean): void;

753 >

754 > // #endregion

755 >

756 > // #region Content provider support

757 > readonly onDidChangeContentProviderSchemes: Event<{ readonly added: string[]; readonly removed: string[] }>;

758 >

759 > getContentProviderSchemes(): string[];

760 >

761 > registerChatSessionContentProvider(scheme: string, provider: IChatSessionContentProvider): IDisposable;

762 > canResolveChatSession(sessionType: string): Promise<boolean>;

763 > getOrCreateChatSession(sessionResource: URI, token: CancellationToken): Promise<IChatSession>;

764 > /** Resolves a parsed response Markdown URI through its session content provider. */

765 > resolveChatResponseUri(sessionResource: URI, href: string, kind: 'link' | 'image'): string;

766 >

767 > /**

768 > * Compute completion items for an input being composed in the chat

769 > * session identified by `sessionResource`. Delegates to the registered

770 > * {@link IChatSessionContentProvider} for the session, if it implements

771 > * {@link IChatSessionContentProvider.provideChatInputCompletions}.

772 > * Returns `undefined` when no provider is available, in which case the

773 > * workbench's default in-process providers should be used.

774 > */

775 > provideChatInputCompletions(sessionResource: URI, params: IChatInputCompletionsParams, token: CancellationToken): Promise<IChatInputCompletionsResult | undefined>;

776 >

777 > /**

778 > * Trigger characters announced by the content provider for the given

779 > * session type. Used to dynamically register Monaco completion

780 > * providers per content-provider scheme. Returns `undefined` when the

781 > * scheme has no content provider, or `[]` when the provider does not

782 > * announce any trigger characters.

783 > */

784 > getChatInputCompletionTriggerCharacters(sessionType: string): Promise<readonly string[] | undefined>;

785 >

786 > getSessionOptions(sessionResource: URI): ReadonlyChatSessionOptionsMap | undefined;

787 > getSessionOption(sessionResource: URI, optionId: string): string | IChatSessionProviderOptionItem | undefined;

788 > setSessionOption(sessionResource: URI, optionId: string, value: string | IChatSessionProviderOptionItem): boolean;

789 > updateSessionOptions(sessionResource: URI, updates: ReadonlyChatSessionOptionsMap): boolean;

790 >

791 > /**

792 > * Fired when options for a chat session change.

793 > */

794 > readonly onDidChangeSessionOptions: Event<IChatSessionOptionsChangeEvent>;

795 >

796 > /**

797 > * Get the capabilities for a specific session type

798 > */

799 > getCapabilitiesForSessionType(chatSessionType: string): IChatAgentAttachmentCapabilities | undefined;

800 >

801 > /**

802 > * Get the customAgentTarget for a specific session type.

803 > * When the Target is not `Target.Undefined`, the mode picker should show filtered custom agents matching this target.

804 > */

805 > getCustomAgentTargetForSessionType(chatSessionType: string): Target;

806 >

807 > /**

808 > * Returns whether the session type requires custom models. When true, the model picker should show filtered custom models.

809 > */

810 > requiresCustomModelsForSessionType(chatSessionType: string): boolean;

811 >

812 > /**

813 > * Returns whether the session type supports the synthetic "Auto" model

814 > * fallback. The built-in local chat always supports it; contributed session

815 > * types default to `false` unless they set `supportsAutoModel`. When false

816 > * and no models are available, the picker shows a "No models available"

817 > * state instead of "Auto".

818 > */

819 > supportsAutoModelForSessionType(chatSessionType: string): boolean;

820 >

821 > /**

822 > * Whether the session type needs a Copilot account and so is unusable until the user signs in (BYOK isn't

823 > * supported). Defaults to false, so third-party types stay usable while signed out.

824 > */

825 > requiresCopilotSignInForSessionType(chatSessionType: string): boolean;

826 >

827 > /**

828 > * Returns whether the session type supports delegation.

829 > * Defaults to true when not explicitly set.

830 > */

831 > supportsDelegationForSessionType(chatSessionType: string): boolean;

832 >

833 > /**

834 > * Returns whether the loaded session supports forking conversations.

835 > */

836 > sessionSupportsFork(sessionResource: URI): boolean;

837 >

838 > /**

839 > * Forks a contributed chat session from the given request point.

840 > * @param sessionResource The session resource to fork.

841 > * @param request The request history item to fork from, or undefined to fork from the end.

842 > * @param token Cancellation token.

843 > * @returns The forked session item, or undefined if forking failed.

844 > */

845 > forkChatSession(sessionResource: URI, request: IChatSessionRequestHistoryItem | undefined, token: CancellationToken): Promise<IChatSessionItem>;

846 >

847 > /**

848 > * Returns whether the loaded session supports renaming.

849 > */

850 > sessionSupportsRename(sessionResource: URI): boolean;

851 >

852 > /**

853 > * Renames a contributed chat session.

854 > * @param sessionResource The session resource to rename.

855 > * @param title The new title for the session.

856 > * @param token Cancellation token.

857 > */

858 > renameChatSession(sessionResource: URI, title: string, token: CancellationToken): Promise<void>;

859 >

860 > readonly onDidChangeOptionGroups: Event<string>;

861 >

862 > getOptionGroupsForSessionType(chatSessionType: string): IChatSessionProviderOptionGroup[] | undefined;

863 > setOptionGroupsForSessionType(chatSessionType: string, handle: number, optionGroups?: readonly IChatSessionProviderOptionGroup[]): void;

864 >

865 > /**

866 > * Get the default options for new sessions of this type, derived from option groups'

867 > * `selected` or `default` items.

868 > */

869 > getNewChatSessionInputState(chatSessionType: string, sessionResource: URI): Promise<readonly IChatSessionProviderOptionGroup[] | undefined>;

870 >

871 > /**

872 > * Creates a new chat session item using the controller's newChatSessionItemHandler.

873 > * Returns undefined if the controller doesn't have a handler or if no controller is registered.

874 > */

875 > createNewChatSessionItem(chatSessionType: string, request: IChatNewSessionRequest, token: CancellationToken): Promise<IChatSessionItem | undefined>;

876 >

877 > /**

878 > * Permanently deletes a chat session item by delegating to the registered controller's `deleteChatSessionItem`

879 > * handler. Throws if the controller does not implement `deleteChatSessionItem`.

880 > */

881 > deleteChatSessionItem(sessionResource: URI, token: CancellationToken): Promise<void>;

882 >

883 > /**

884 > * Records the inverse `real → untitled` alias so option lookups for the real

885 > * session resolve to the untitled session's entry (e.g. {@link updateSessionOptions}).

886 > *

887 > * Call this BEFORE the real session loads, and never remove it — the real

888 > * session keeps reading its options through this alias even after the untitled

889 > * model is disposed. (Only the forward mapping is cleared, via

890 > * {@link clearMaterializedSessionResource}.) Publishing the forward mapping is a

891 > * separate step; see {@link setMaterializedSessionResource}.

892 > */

893 > registerSessionResourceAlias(untitledResource: URI, realResource: URI): void;

894 >

895 > /**

896 > * Records the forward `untitled → real` mapping (read via

897 > * {@link getMaterializedSessionResource}) so a late send still addressed to the

898 > * untitled resource re-targets the real session. Call this only AFTER the real

899 > * session has loaded.

900 > *

901 > * Kept separate from {@link registerSessionResourceAlias} on purpose: the

902 > * inverse alias must exist BEFORE the load (for option lookups), but this

903 > * forward mapping must appear only AFTER the real session exists — published

904 > * earlier, a failed or still-loading session would be re-targeted before it

905 > * exists (a later send would throw "Unknown session").

906 > */

907 > setMaterializedSessionResource(untitledResource: URI, realResource: URI): void;

908 >

909 > /**

910 > * Returns the real session resource that `untitledResource` materialized

911 > * into (via {@link setMaterializedSessionResource}), or `undefined` if it has

912 > * not materialized or the mapping was already cleared.

913 > */

914 > getMaterializedSessionResource(untitledResource: URI): URI | undefined;

915 >

916 > /**

917 > * Clears the forward `untitled → real` mapping for `sessionResource` (passed

918 > * either the untitled key or the real value), so {@link getMaterializedSessionResource}

919 > * stops re-targeting once the session is disposed. Does NOT remove the inverse

920 > * alias, which is intentionally permanent (see {@link registerSessionResourceAlias}).

921 > */

922 > clearMaterializedSessionResource(sessionResource: URI): void;

923 >

924 > /**

925 > * Fires {@link onDidCommitSession} to notify listeners that an untitled

926 > * session has been committed with a real resource URI.

927 > */

928 > fireSessionCommitted(original: URI, committed: URI): void;

929 >

930 > // #region Customizations provider support

931 > readonly onDidChangeCustomizations: Event<{ readonly chatSessionType: string }>;

932 > registerCustomizationsProvider(chatSessionType: string, provider: IChatSessionCustomizationsProvider): IDisposable;

933 > hasCustomizationsProvider(chatSessionType: string): boolean;

934 > getCustomizations(chatSessionType: string, token: CancellationToken): Promise<IChatSessionCustomizationItemGroup[] | undefined>;

935 > // #endregion

936 > }

937 >

938 > export function isSessionInProgressStatus(state: ChatSessionStatus): boolean {

939 return state === ChatSessionStatus.InProgress || state === ChatSessionStatus.NeedsInput;

940 }

941 > chatSessionsService.ts

942 > export function isIChatSessionFileChange2(obj: unknown): obj is IChatSessionFileChange2 {

943 > const candidate = obj as IChatSessionFileChange2; chatSessionsService.ts

944 > return candidate && candidate.uri instanceof URI && typeof candidate.insertions === 'number' && typeof candidate.deletions === 'number';

945 > }

1 > /*--------------------------------------------------------------------------------------------- event.ts

2 > * Copyright (c) Microsoft Corporation. All rights reserved.

3 > * Licensed under the MIT License. See License.txt in the project root for license information.

4 > *--------------------------------------------------------------------------------------------*/

5 >

6 > import { CancelablePromise } from './async.js';

7 > import { CancellationToken } from './cancellation.js';

8 > import { diffSets } from './collections.js';

9 > import { onUnexpectedError } from './errors.js';

10 > import { createSingleCallFunction } from './functional.js';

11 > import { combinedDisposable, Disposable, DisposableMap, DisposableStore, IDisposable, toDisposable } from './lifecycle.js';

12 > import { LinkedList } from './linkedList.js';

13 > import { IObservable, IObservableWithChange, IObserver } from './observable.js';

14 > import { env } from './process.js';

15 > import { StopWatch } from './stopwatch.js';

16 > import { MicrotaskDelay } from './symbols.js';

17 >

18 >

19 > // -----------------------------------------------------------------------------------------------------------------------

20 > // Uncomment the next line to print warnings whenever an emitter with listeners is disposed. That is a sign of code smell.

21 > // -----------------------------------------------------------------------------------------------------------------------

22 > const _enableDisposeWithListenerWarning = false

23 > // || Boolean("TRUE") // causes a linter warning so that it cannot be pushed

24 > ;

25 >

26 >

27 > // -----------------------------------------------------------------------------------------------------------------------

28 > // Uncomment the next line to print warnings whenever a snapshotted event is used repeatedly without cleanup.

29 > // See https://github.com/microsoft/vscode/issues/142851

30 > // -----------------------------------------------------------------------------------------------------------------------

31 > const _enableSnapshotPotentialLeakWarning = false

32 > // || Boolean("TRUE") // causes a linter warning so that it cannot be pushed

33 > ;

34 >

35 >

36 > const _bufferLeakWarnCountThreshold = 100;

37 > const _bufferLeakWarnTimeThreshold = 60_000; // 1 minute

38 >

39 function _isBufferLeakWarningEnabled(): boolean {

40 return !!env['VSCODE_DEV'];

41 }

42 > event.ts

43 > /**

44 > * An event with zero or one parameters that can be subscribed to. The event is a function itself.

45 > */

46 > export interface Event<T> {

47 > (listener: (e: T) => unknown, thisArgs?: any, disposables?: IDisposable[] | DisposableStore): IDisposable;

48 > }

49 >

50 > export namespace Event {

51 > export const None: Event<any> = () => Disposable.None;

52 >

53 > function _addLeakageTraceLogic(options: EmitterOptions) {

54 if (_enableSnapshotPotentialLeakWarning) {

55 const { onDidAddListener: origListenerDidAdd } = options;

65 }

66 }

67 > event.ts

68 > /**

69 > * Given an event, returns another event which debounces calls and defers the listeners to a later task via a shared

70 > * `setTimeout`. The event is converted into a signal (`Event<void>`) to avoid additional object creation as a

71 > * result of merging events and to try prevent race conditions that could arise when using related deferred and

72 > * non-deferred events.

73 > *

74 > * This is useful for deferring non-critical work (eg. general UI updates) to ensure it does not block critical work

75 > * (eg. latency of keypress to text rendered).

76 > *

77 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

78 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

79 > * returned event causes this utility to leak a listener on the original event.

80 > *

81 > * @param event The event source for the new event.

82 > * @param flushOnListenerRemove Whether to fire all debounced events when a listener is removed. If this is not

83 > * specified, some events could go missing. Use this if it's important that all events are processed, even if the

84 > * listener gets disposed before the debounced event fires.

85 > * @param disposable A disposable store to add the new EventEmitter to.

86 > */

87 > export function defer(event: Event<unknown>, flushOnListenerRemove?: boolean, disposable?: DisposableStore): Event<void> {

88 return debounce<unknown, void>(event, () => void 0, 0, undefined, flushOnListenerRemove ?? true, undefined, disposable);

89 }

90 > event.ts

91 > /**

92 > * Given an event, returns another event which only fires once.

93 > *

94 > * @param event The event source for the new event.

95 > */

96 > export function once<T>(event: Event<T>): Event<T> {

97 return (listener, thisArgs = null, disposables?) => {

98 // we need this, in case the event fires during the listener call

118 };

119 }

120 > event.ts

121 > /**

122 > * Given an event, returns another event which only fires once, and only when the condition is met.

123 > *

124 > * @param event The event source for the new event.

125 > */

126 > export function onceIf<T>(event: Event<T>, condition: (e: T) => boolean): Event<T> {

127 return Event.once(Event.filter(event, condition));

128 }

129 > event.ts

130 > /**

131 > * Maps an event of one type into an event of another type using a mapping function, similar to how

132 > * `Array.prototype.map` works.

133 > *

134 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

135 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

136 > * returned event causes this utility to leak a listener on the original event.

137 > *

138 > * @param event The event source for the new event.

139 > * @param map The mapping function.

140 > * @param disposable A disposable store to add the new EventEmitter to.

141 > */

142 > export function map<I, O>(event: Event<I>, map: (i: I) => O, disposable?: DisposableStore): Event<O> {

143 return snapshot((listener, thisArgs = null, disposables?) => event(i => listener.call(thisArgs, map(i)), null, disposables), disposable);

144 }

145 > event.ts

146 > /**

147 > * Wraps an event in another event that performs some function on the event object before firing.

148 > *

149 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

150 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

151 > * returned event causes this utility to leak a listener on the original event.

152 > *

153 > * @param event The event source for the new event.

154 > * @param each The function to perform on the event object.

155 > * @param disposable A disposable store to add the new EventEmitter to.

156 > */

157 > export function forEach<I>(event: Event<I>, each: (i: I) => void, disposable?: DisposableStore): Event<I> {

158 return snapshot((listener, thisArgs = null, disposables?) => event(i => { each(i); listener.call(thisArgs, i); }, null, disposables), disposable);

159 }

160 > event.ts

161 > /**

162 > * Wraps an event in another event that fires only when some condition is met.

163 > *

164 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

165 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

166 > * returned event causes this utility to leak a listener on the original event.

167 > *

168 > * @param event The event source for the new event.

169 > * @param filter The filter function that defines the condition. The event will fire for the object if this function

170 > * returns true.

171 > * @param disposable A disposable store to add the new EventEmitter to.

172 > */

173 > export function filter<T, U>(event: Event<T | U>, filter: (e: T | U) => e is T, disposable?: DisposableStore): Event<T>;

174 > export function filter<T>(event: Event<T>, filter: (e: T) => boolean, disposable?: DisposableStore): Event<T>;

175 > export function filter<T, R>(event: Event<T | R>, filter: (e: T | R) => e is R, disposable?: DisposableStore): Event<R>;

176 > export function filter<T>(event: Event<T>, filter: (e: T) => boolean, disposable?: DisposableStore): Event<T> {

177 return snapshot((listener, thisArgs = null, disposables?) => event(e => filter(e) && listener.call(thisArgs, e), null, disposables), disposable);

178 }

179 > event.ts

180 > /**

181 > * Given an event, returns the same event but typed as `Event<void>`.

182 > */

183 > export function signal<T>(event: Event<T>): Event<void> {

184 return event as Event<any> as Event<void>;

185 }

186 > event.ts

187 > /**

188 > * Given a collection of events, returns a single event which emits whenever any of the provided events emit.

189 > */

190 > export function any<T>(...events: Event<T>[]): Event<T>;

191 > export function any(...events: Event<any>[]): Event<void>;

192 > export function any<T>(...events: Event<T>[]): Event<T> {

193 return (listener, thisArgs = null, disposables?) => {

194 const disposable = combinedDisposable(...events.map(event => event(e => listener.call(thisArgs, e))));

196 };

197 }

198 > event.ts

199 > /**

200 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

201 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

202 > * returned event causes this utility to leak a listener on the original event.

203 > */

204 > export function reduce<I, O>(event: Event<I>, merge: (last: O | undefined, event: I) => O, initial?: O, disposable?: DisposableStore): Event<O> {

205 let output: O | undefined = initial;

206

210 }, disposable);

211 }

212 > event.ts

213 > function snapshot<T>(event: Event<T>, disposable: DisposableStore | undefined): Event<T> {

214 let listener: IDisposable | undefined;

215

233 return emitter.event;

234 }

235 > event.ts

236 > /**

237 > * Adds the IDisposable to the store if it's set, and returns it. Useful to

238 > * Event function implementation.

239 > */

240 > function addAndReturnDisposable<T extends IDisposable>(d: T, store: DisposableStore | IDisposable[] | undefined): T {

241 if (store instanceof Array) {

242 store.push(d);

246 return d;

247 }

248 > event.ts

249 > /**

250 > * Given an event, creates a new emitter that event that will debounce events based on {@link delay} and give an

251 > * array event object of all events that fired.

252 > *

253 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

254 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

255 > * returned event causes this utility to leak a listener on the original event.

256 > *

257 > * @param event The original event to debounce.

258 > * @param merge A function that reduces all events into a single event.

259 > * @param delay The number of milliseconds to debounce.

260 > * @param leading Whether to fire a leading event without debouncing.

261 > * @param flushOnListenerRemove Whether to fire all debounced events when a listener is removed. If this is not

262 > * specified, some events could go missing. Use this if it's important that all events are processed, even if the

263 > * listener gets disposed before the debounced event fires.

264 > * @param leakWarningThreshold See {@link EmitterOptions.leakWarningThreshold}.

265 > * @param disposable A disposable store to register the debounce emitter to.

266 > */

267 > export function debounce<T>(event: Event<T>, merge: (last: T | undefined, event: T) => T, delay?: number | typeof MicrotaskDelay, leading?: boolean, flushOnListenerRemove?: boolean, leakWarningThreshold?: number, disposable?: DisposableStore): Event<T>;

268 > export function debounce<I, O>(event: Event<I>, merge: (last: O | undefined, event: I) => O, delay?: number | typeof MicrotaskDelay, leading?: boolean, flushOnListenerRemove?: boolean, leakWarningThreshold?: number, disposable?: DisposableStore): Event<O>;

269 > export function debounce<I, O>(event: Event<I>, merge: (last: O | undefined, event: I) => O, delay: number | typeof MicrotaskDelay = 100, leading = false, flushOnListenerRemove = false, leakWarningThreshold?: number, disposable?: DisposableStore): Event<O> {

270 let subscription: IDisposable;

271 let output: O | undefined = undefined;

330 return emitter.event;

331 }

332 > event.ts

333 > /**

334 > * Debounces an event, firing after some delay (default=0) with an array of all event original objects.

335 > *

336 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

337 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

338 > * returned event causes this utility to leak a listener on the original event.

339 > *

340 > * @param event The event source for the new event.

341 > * @param delay The number of milliseconds to debounce.

342 > * @param flushOnListenerRemove Whether to fire all debounced events when a listener is removed. If this is not

343 > * specified, some events could go missing. Use this if it's important that all events are processed, even if the

344 > * listener gets disposed before the debounced event fires.

345 > * @param disposable A disposable store to add the new EventEmitter to.

346 > */

347 > export function accumulate<T>(event: Event<T>, delay: number | typeof MicrotaskDelay = 0, flushOnListenerRemove?: boolean, disposable?: DisposableStore): Event<T[]> {

348 return Event.debounce<T, T[]>(event, (last, e) => {

349 if (!last) {

354 }, delay, undefined, flushOnListenerRemove ?? true, undefined, disposable);

355 }

356 > event.ts

357 > /**

358 > * Throttles an event, ensuring the event is fired at most once during the specified delay period.

359 > * Unlike debounce, throttle will fire immediately on the leading edge and/or after the delay on the trailing edge.

360 > *

361 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

362 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

363 > * returned event causes this utility to leak a listener on the original event.

364 > *

365 > * @param event The event source for the new event.

366 > * @param merge An accumulator function that merges events if multiple occur during the throttle period.

367 > * @param delay The number of milliseconds to throttle.

368 > * @param leading Whether to fire on the leading edge (immediately on first event).

369 > * @param trailing Whether to fire on the trailing edge (after delay with the last value).

370 > * @param leakWarningThreshold See {@link EmitterOptions.leakWarningThreshold}.

371 > * @param disposable A disposable store to register the throttle emitter to.

372 > */

373 > export function throttle<T>(event: Event<T>, merge: (last: T | undefined, event: T) => T, delay?: number | typeof MicrotaskDelay, leading?: boolean, trailing?: boolean, leakWarningThreshold?: number, disposable?: DisposableStore): Event<T>;

374 > export function throttle<I, O>(event: Event<I>, merge: (last: O | undefined, event: I) => O, delay?: number | typeof MicrotaskDelay, leading?: boolean, trailing?: boolean, leakWarningThreshold?: number, disposable?: DisposableStore): Event<O>;

375 > export function throttle<I, O>(event: Event<I>, merge: (last: O | undefined, event: I) => O, delay: number | typeof MicrotaskDelay = 100, leading = true, trailing = true, leakWarningThreshold?: number, disposable?: DisposableStore): Event<O> {

376 let subscription: IDisposable;

377 let output: O | undefined = undefined;

437 return emitter.event;

438 }

439 > event.ts

440 > /**

441 > * Filters an event such that some condition is _not_ met more than once in a row, effectively ensuring duplicate

442 > * event objects from different sources do not fire the same event object.

443 > *

444 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

445 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

446 > * returned event causes this utility to leak a listener on the original event.

447 > *

448 > * @param event The event source for the new event.

449 > * @param equals The equality condition.

450 > * @param disposable A disposable store to add the new EventEmitter to.

451 > *

452 > * @example

453 > * ```

454 > * // Fire only one time when a single window is opened or focused

455 > * Event.latch(Event.any(onDidOpenWindow, onDidFocusWindow))

456 > * ```

457 > */

458 > export function latch<T>(event: Event<T>, equals: (a: T, b: T) => boolean = (a, b) => a === b, disposable?: DisposableStore): Event<T> {

459 let firstCall = true;

460 let cache: T;

467 }, disposable);

468 }

469 > event.ts

470 > /**

471 > * Splits an event whose parameter is a union type into 2 separate events for each type in the union.

472 > *

473 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

474 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

475 > * returned event causes this utility to leak a listener on the original event.

476 > *

477 > * @example

478 > * ```

479 > * const event = new EventEmitter<number | undefined>().event;

480 > * const [numberEvent, undefinedEvent] = Event.split(event, isUndefined);

481 > * ```

482 > *

483 > * @param event The event source for the new event.

484 > * @param isT A function that determines what event is of the first type.

485 > * @param disposable A disposable store to add the new EventEmitter to.

486 > */

487 > export function split<T, U>(event: Event<T | U>, isT: (e: T | U) => e is T, disposable?: DisposableStore): [Event<T>, Event<U>] {

488 return [

489 Event.filter(event, isT, disposable),

491 ];

492 }

493 > event.ts

494 > /**

495 > * Buffers an event until it has a listener attached.

496 > *

497 > * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned

498 > * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the

499 > * returned event causes this utility to leak a listener on the original event.

500 > *

501 > * @param event The event source for the new event.

502 > * @param debugName A name for this buffer, used in leak detection warnings.

503 > * @param flushAfterTimeout Determines whether to flush the buffer after a timeout immediately or after a

504 > * `setTimeout` when the first event listener is added.

505 > * @param _buffer Internal: A source event array used for tests.

506 > *

507 > * @example

508 > * ```

509 > * // Start accumulating events, when the first listener is attached, flush

510 > * // the event after a timeout such that multiple listeners attached before

511 > * // the timeout would receive the event

512 > * this.onInstallExtension = Event.buffer(service.onInstallExtension, 'onInstallExtension', true);

513 > * ```

514 > */

515 > export function buffer<T>(event: Event<T>, debugName: string, flushAfterTimeout = false, _buffer: T[] = [], disposable?: DisposableStore): Event<T> {

516 let buffer: T[] | null = _buffer.slice();

517

600 return emitter.event;

601 }

602 > /** event.ts

603 > * Wraps the event in an {@link IChainableEvent}, allowing a more functional programming style.

604 > *

605 > * @example

606 > * ```

607 > * // Normal

608 > * const onEnterPressNormal = Event.filter(

609 > * Event.map(onKeyPress.event, e => new StandardKeyboardEvent(e)),

610 > * e.keyCode === KeyCode.Enter

611 > * ).event;

612 > *

613 > * // Using chain

614 > * const onEnterPressChain = Event.chain(onKeyPress.event, $ => $

615 > * .map(e => new StandardKeyboardEvent(e))

616 > * .filter(e => e.keyCode === KeyCode.Enter)

617 > * );

618 > * ```

619 > */

620 > export function chain<T, R>(event: Event<T>, sythensize: ($: IChainableSythensis<T>) => IChainableSythensis<R>): Event<R> {

621 const fn: Event<R> = (listener, thisArgs, disposables) => {

622 const cs = sythensize(new ChainableSynthesis()) as ChainableSynthesis;

631 return fn;

632 }

633 > event.ts

634 > const HaltChainable = Symbol('HaltChainable');

635 >

636 > class ChainableSynthesis implements IChainableSythensis<any> {

637 private readonly steps: ((input: any) => unknown)[] = [];

638 > event.ts

639 > map<O>(fn: (i: any) => O): this {

640 this.steps.push(fn);

641 return this;

642 }

643 > event.ts

644 > forEach(fn: (i: any) => void): this {

645 this.steps.push(v => {

646 fn(v);

649 return this;

650 }

651 > event.ts

652 > filter(fn: (e: any) => boolean): this {

653 this.steps.push(v => fn(v) ? v : HaltChainable);

654 return this;

655 }

656 > event.ts

657 > reduce<R>(merge: (last: R | undefined, event: any) => R, initial?: R | undefined): this {

658 let last = initial;

659 this.steps.push(v => {

663 return this;

664 }

665 > event.ts

666 > latch(equals: (a: any, b: any) => boolean = (a, b) => a === b): ChainableSynthesis {

667 let firstCall = true;

668 let cache: any;

676 return this;

677 }

678 > event.ts

679 > public evaluate(value: any) {

680 for (const step of this.steps) {

681 value = step(value);

687 return value;

688 }

689 > } event.ts

690 >

691 > export interface IChainableSythensis<T> {

692 > map<O>(fn: (i: T) => O): IChainableSythensis<O>;

693 > forEach(fn: (i: T) => void): IChainableSythensis<T>;

694 > filter<R extends T>(fn: (e: T) => e is R): IChainableSythensis<R>;

695 > filter(fn: (e: T) => boolean): IChainableSythensis<T>;

696 > reduce<R>(merge: (last: R, event: T) => R, initial: R): IChainableSythensis<R>;

697 > reduce<R>(merge: (last: R | undefined, event: T) => R): IChainableSythensis<R>;

698 > latch(equals?: (a: T, b: T) => boolean): IChainableSythensis<T>;

699 > }

700 >

701 > export interface NodeEventEmitter {

702 > on(event: string | symbol, listener: Function): unknown;

703 > removeListener(event: string | symbol, listener: Function): unknown;

704 > }

705 >

706 > /**

707 > * Creates an {@link Event} from a node event emitter.

708 > */

709 > export function fromNodeEventEmitter<T>(emitter: NodeEventEmitter, eventName: string, map: (...args: any[]) => T = id => id): Event<T> {

710 const fn = (...args: unknown[]) => result.fire(map(...args));

711 const onFirstListenerAdd = () => emitter.on(eventName, fn);

715 return result.event;

716 }

717 > event.ts

718 > export interface DOMEventEmitter {

719 > addEventListener(event: string | symbol, listener: Function): void;

720 > removeEventListener(event: string | symbol, listener: Function): void;

721 > }

722 >

723 > /**

724 > * Creates an {@link Event} from a DOM event emitter.

725 > */

726 > export function fromDOMEventEmitter<T>(emitter: DOMEventEmitter, eventName: string, map: (...args: any[]) => T = id => id): Event<T> {

727 const fn = (...args: unknown[]) => result.fire(map(...args));

728 const onFirstListenerAdd = () => emitter.addEventListener(eventName, fn);

732 return result.event;

733 }

734 > event.ts

735 > /**

736 > * Creates a promise out of an event, using the {@link Event.once} helper.

737 > */

738 > export function toPromise<T>(event: Event<T>, disposables?: IDisposable[] | DisposableStore): CancelablePromise<T> {

739 let cancelRef: () => void;

740 let listener: IDisposable;

756 return promise;

757 }

758 > event.ts

759 > /**

760 > * A convenience function for forwarding an event to another emitter which

761 > * improves readability.

762 > *

763 > * This is similar to {@link Relay} but allows instantiating and forwarding

764 > * on a single line and also allows for multiple source events.

765 > * @param from The event to forward.

766 > * @param to The emitter to forward the event to.

767 > * @example

768 > * Event.forward(event, emitter);

769 > * // equivalent to

770 > * event(e => emitter.fire(e));

771 > * // equivalent to

772 > * event(emitter.fire, emitter);

773 > */

774 > export function forward<T>(from: Event<T>, to: Emitter<T>): IDisposable {

775 return from(e => to.fire(e));

776 }

777 > event.ts

778 > /**

779 > * Adds a listener to an event and calls the listener immediately with undefined as the event object.

780 > *

781 > * @example

782 > * ```

783 > * // Initialize the UI and update it when dataChangeEvent fires

784 > * runAndSubscribe(dataChangeEvent, () => this._updateUI());

785 > * ```

786 > */

787 > export function runAndSubscribe<T>(event: Event<T>, handler: (e: T) => unknown, initial: T): IDisposable;

788 > export function runAndSubscribe<T>(event: Event<T>, handler: (e: T | undefined) => unknown): IDisposable;

789 > export function runAndSubscribe<T>(event: Event<T>, handler: (e: T | undefined) => unknown, initial?: T): IDisposable {

790 handler(initial);

791 return event(e => handler(e));

792 }

793 > event.ts

794 > class EmitterObserver<T> implements IObserver {

795 >

796 > readonly emitter: Emitter<T>;

797 >

798 > private _counter = 0;

799 > private _hasChanged = false;

800 >

801 > constructor(readonly _observable: IObservable<T>, store: DisposableStore | undefined) {

802 const options: EmitterOptions = {

803 onWillAddFirstListener: () => {

819 }

820 }

821 > event.ts

822 > beginUpdate<T>(_observable: IObservable<T>): void {

823 // assert(_observable === this.obs);

824 this._counter++;

825 }

826 > event.ts

827 > handlePossibleChange<T>(_observable: IObservable<T>): void {

828 // assert(_observable === this.obs);

829 }

830 > event.ts

831 > handleChange<T, TChange>(_observable: IObservableWithChange<T, TChange>, _change: TChange): void {

832 // assert(_observable === this.obs);

833 this._hasChanged = true;

834 }

835 > event.ts

836 > endUpdate<T>(_observable: IObservable<T>): void {

837 // assert(_observable === this.obs);

838 this._counter--;

845 }

846 }

847 > } event.ts

848 >

849 > /**

850 > * Creates an event emitter that is fired when the observable changes.

851 > * Each listeners subscribes to the emitter.

852 > */

853 > export function fromObservable<T>(obs: IObservable<T>, store?: DisposableStore): Event<T> {

854 const observer = new EmitterObserver(obs, store);

855 return observer.emitter.event;

856 }

857 > event.ts

858 > /**

859 > * Each listener is attached to the observable directly.

860 > */

861 > export function fromObservableLight(observable: IObservable<unknown>): Event<void> {

862 return (listener, thisArgs, disposables) => {

863 let count = 0;

897 };

898 }

899 > } event.ts

900 >

901 > export interface EmitterOptions {

902 > /**

903 > * Optional function that's called *before* the very first listener is added

904 > */

905 > onWillAddFirstListener?: Function;

906 > /**

907 > * Optional function that's called *after* the very first listener is added

908 > */

909 > onDidAddFirstListener?: Function;

910 > /**

911 > * Optional function that's called after a listener is added

912 > */

913 > onDidAddListener?: Function;

914 > /**

915 > * Optional function that's called *after* remove the very last listener

916 > */

917 > onDidRemoveLastListener?: Function;

918 > /**

919 > * Optional function that's called *before* a listener is removed

920 > */

921 > onWillRemoveListener?: Function;

922 > /**

923 > * Optional function that's called when a listener throws an error. Defaults to

924 > * {@link onUnexpectedError}

925 > */

926 > onListenerError?: (e: any) => void;

927 > /**

928 > * Number of listeners that are allowed before assuming a leak. Default to

929 > * a globally configured value

930 > *

931 > * @see setGlobalLeakWarningThreshold

932 > */

933 > leakWarningThreshold?: number;

934 > /**

935 > * Human-readable name for the emitter, included in leak warning error

936 > * messages to help identify which emitter is leaking in telemetry.

937 > */

938 > leakWarningName?: string;

939 > /**

940 > * Pass in a delivery queue, which is useful for ensuring

941 > * in order event delivery across multiple emitters.

942 > */

943 > deliveryQueue?: EventDeliveryQueue;

944 >

945 > /** ONLY enable this during development */

946 > _profName?: string;

947 > }

948 >

949 >

950 > export class EventProfiling {

951 >

952 > static readonly all = new Set<EventProfiling>();

953 >

954 > private static _idPool = 0;

955 >

956 > readonly name: string;

957 > public listenerCount: number = 0;

958 > public invocationCount = 0;

959 > public elapsedOverall = 0;

960 > public durations: number[] = [];

961 >

962 > private _stopWatch?: StopWatch;

963 >

964 > constructor(name: string) {

965 this.name = `${name}_${EventProfiling._idPool++}`;

966 EventProfiling.all.add(this);

967 }

968 > event.ts

969 > start(listenerCount: number): void {

970 this._stopWatch = new StopWatch();

971 this.listenerCount = listenerCount;

972 }

973 > event.ts

974 > stop(): void {

975 if (this._stopWatch) {

976 const elapsed = this._stopWatch.elapsed();

981 }

982 }

983 > } event.ts

984 >

985 > let _globalLeakWarningThreshold = -1;

986 > export function setGlobalLeakWarningThreshold(n: number): IDisposable {

987 const oldValue = _globalLeakWarningThreshold;

988 _globalLeakWarningThreshold = n;

993 };

994 }

995 > event.ts

996 > class LeakageMonitor {

997 >

998 > private static _idPool = 1;

999 >

1000 > private _stacks: Map<string, number> | undefined;

1001 > private _warnCountdown: number = 0;

1002 >

1003 > constructor(

1004 private readonly _errorHandler: (err: Error) => void,

1005 readonly threshold: number,

1006 readonly name: string = (LeakageMonitor._idPool++).toString(16).padStart(3, '0')

1007 ) { }

1008 > event.ts

1009 > dispose(): void {

1010 this._stacks?.clear();

1011 }

1012 > event.ts

1013 > check(stack: Stacktrace, listenerCount: number): undefined | (() => void) {

1014

1015 const threshold = this.threshold;

1046 };

1047 }

1048 > event.ts

1049 > getMostFrequentStack(): [string, number] | undefined {

1050 if (!this._stacks) {

1051 return undefined;

1061 return topStack;

1062 }

1063 > } event.ts

1064 >

1065 > class Stacktrace {

1066 >

1067 > static create() {

1068 > const err = new Error();

1069 > return new Stacktrace(err.stack ?? '');

1070 > }

1071 >

1072 > private constructor(readonly value: string) { }

1073 >

1074 > print() {

1075 console.warn(this.value.split('\n').slice(2).join('\n'));

1076 }

1077 > } event.ts

1078 >

1079 > // error that is logged when going over the configured listener threshold

1080 > export class ListenerLeakError extends Error {

1081 > readonly kind: string;

1082 > readonly listenerCount: number;

1083 > /**

1084 > * The detailed message including listener count and most frequent stack.

1085 > * Available locally for debugging but intentionally not used as the error

1086 > * `message`. When `emitterName` is provided, errors group by emitter name

1087 > * and kind in telemetry; otherwise they group by kind alone.

1088 > */

1089 > readonly details: string;

1090 > constructor(kind: 'dominated' | 'popular', details: string, stack: string, listenerCount: number, emitterName?: string) {

1091 super(emitterName

1092 ? `[${emitterName}] potential listener LEAK detected, ${kind}`

1098 this.stack = stack;

1099 }

1100 > event.ts

1101 > static is(err: unknown): err is ListenerLeakError {

1102 return err instanceof ListenerLeakError

1103 || (err instanceof Error && typeof (err as Error & { kind: unknown; listenerCount: unknown }).kind === 'string' && typeof (err as Error & { kind: unknown; listenerCount: unknown }).listenerCount === 'number');

1104 }

1105 > } event.ts

1106 >

1107 > // SEVERE error that is logged when having gone way over the configured listener

1108 > // threshold so that the emitter refuses to accept more listeners

1109 > export class ListenerRefusalError extends ListenerLeakError {

1110 > constructor(kind: 'dominated' | 'popular', details: string, stack: string, listenerCount: number, emitterName?: string) {

1111 super(kind, details, stack, listenerCount, emitterName);

1112 this.name = 'ListenerRefusalError';

1113 }

1114 > } event.ts

1115 >

1116 > let id = 0;

1117 > class UniqueContainer<T> {

1118 > stack?: Stacktrace;

1119 > public id = id++;

1120 > constructor(public readonly value: T) { }

1121 > }

1122 > const compactionThreshold = 2;

1123 >

1124 > type ListenerContainer<T> = UniqueContainer<(data: T) => void>;

1125 > type ListenerOrListeners<T> = (ListenerContainer<T> | undefined)[] | ListenerContainer<T>;

1126 >

1127 > const forEachListener = <T>(listeners: ListenerOrListeners<T>, fn: (c: ListenerContainer<T>) => void) => {

1128 if (listeners instanceof UniqueContainer) {

1129 fn(listeners);

1137 }

1138 };

1139 > event.ts

1140 > /**

1141 > * The Emitter can be used to expose an Event to the public

1142 > * to fire it from the insides.

1143 > * Sample:

1144 > class Document {

1145 >

1146 > private readonly _onDidChange = new Emitter<(value:string)=>any>();

1147 >

1148 > public onDidChange = this._onDidChange.event;

1149 >

1150 > // getter-style

1151 > // get onDidChange(): Event<(value:string)=>any> {

1152 > // return this._onDidChange.event;

1153 > // }

1154 >

1155 > private _doIt() {

1156 > //...

1157 > this._onDidChange.fire(value);

1158 > }

1159 > }

1160 > */

1161 > export class Emitter<T> {

1162 >

1163 > private readonly _options?: EmitterOptions;

1164 > private readonly _leakageMon?: LeakageMonitor;

1165 > private readonly _perfMon?: EventProfiling;

1166 > private _disposed?: true;

1167 > private _event?: Event<T>;

1168 >

1169 > /**

1170 > * A listener, or list of listeners. A single listener is the most common

1171 > * for event emitters (#185789), so we optimize that special case to avoid

1172 > * wrapping it in an array (just like Node.js itself.)

1173 > *

1174 > * A list of listeners never 'downgrades' back to a plain function if

1175 > * listeners are removed, for two reasons:

1176 > *

1177 > * 1. That's complicated (especially with the deliveryQueue)

1178 > * 2. A listener with >1 listener is likely to have >1 listener again at

1179 > * some point, and swapping between arrays and functions may[citation needed]

1180 > * introduce unnecessary work and garbage.

1181 > *

1182 > * The array listeners can be 'sparse', to avoid reallocating the array

1183 > * whenever any listener is added or removed. If more than `1 / compactionThreshold`

1184 > * of the array is empty, only then is it resized.

1185 > */

1186 > protected _listeners?: ListenerOrListeners<T>;

1187 >

1188 > /**

1189 > * Always to be defined if _listeners is an array. It's no longer a true

1190 > * queue, but holds the dispatching 'state'. If `fire()` is called on an

1191 > * emitter, any work left in the _deliveryQueue is finished first.

1192 > */

1193 > private _deliveryQueue?: EventDeliveryQueuePrivate;

1194 > protected _size = 0;

1195 >

1196 > constructor(options?: EmitterOptions) {

1197 this._options = options;

1198 this._leakageMon = (_globalLeakWarningThreshold > 0 || this._options?.leakWarningThreshold)

1202 this._deliveryQueue = this._options?.deliveryQueue as EventDeliveryQueuePrivate | undefined;

1203 }

1204 > event.ts

1205 > dispose() {

1206 if (!this._disposed) {

1207 this._disposed = true;

1235 }

1236 }

1237 > event.ts

1238 > /**

1239 > * For the public to allow to subscribe

1240 > * to events from this Emitter

1241 > */

1242 > get event(): Event<T> {

1243 this._event ??= (callback: (e: T) => unknown, thisArgs?: any, disposables?: IDisposable[] | DisposableStore) => {

1244 if (this._leakageMon && this._size > this._leakageMon.threshold ** 2) {

1304 return this._event;

1305 }

1306 > event.ts

1307 > private _removeListener(listener: ListenerContainer<T>) {

1308 this._options?.onWillRemoveListener?.(this);

1309

1349 }

1350 }

1351 > event.ts

1352 > private _deliver(listener: undefined | UniqueContainer<(value: T) => void>, value: T) {

1353 if (!listener) {

1354 return;

1367 }

1368 }

1369 > event.ts

1370 > /** Delivers items in the queue. Assumes the queue is ready to go. */

1371 > private _deliverQueue(dq: EventDeliveryQueuePrivate) {

1372 const listeners = dq.current!._listeners! as (ListenerContainer<T> | undefined)[];

1373 while (dq.i < dq.end) {

1377 dq.reset();

1378 }

1379 > event.ts

1380 > /**

1381 > * To be kept private to fire an event to

1382 > * subscribers

1383 > */

1384 > fire(event: T): void {

1385 if (this._deliveryQueue?.current) {

1386 this._deliverQueue(this._deliveryQueue);

1402 this._perfMon?.stop();

1403 }

1404 > event.ts

1405 > hasListeners(): boolean {

1406 return this._size > 0;

1407 }

1408 > } event.ts

1409 >

1410 > export interface EventDeliveryQueue {

1411 > _isEventDeliveryQueue: true;

1412 > }

1413 >

1414 > export const createEventDeliveryQueue = (): EventDeliveryQueue => new EventDeliveryQueuePrivate();

1415 >

1416 class EventDeliveryQueuePrivate implements EventDeliveryQueue {

1417 declare _isEventDeliveryQueue: true;

1426 */

1427 public end = 0;

1428 > event.ts

1429 > /**

1430 > * Emitter currently being dispatched on. Emitter._listeners is always an array.

1431 > */

1432 > public current?: Emitter<any>;

1433 > /**

1434 > * Currently emitting value. Defined whenever `current` is.

1435 > */

1436 > public value?: unknown;

1437 >

1438 > public enqueue<T>(emitter: Emitter<T>, value: T, end: number) {

1439 this.i = 0;

1440 this.end = end;

1442 this.value = value;

1443 }

1444 > event.ts

1445 > public reset() {

1446 this.i = this.end; // force any current emission loop to stop, mainly for during dispose

1447 this.current = undefined;

1448 this.value = undefined;

1449 }

1450 > } event.ts

1451 >

1452 > export interface IWaitUntil {

1453 > token: CancellationToken;

1454 > waitUntil(thenable: Promise<unknown>): void;

1455 > }

1456 >

1457 > export type IWaitUntilData<T> = Omit<Omit<T, 'waitUntil'>, 'token'>;

1458 >

1459 > export class AsyncEmitter<T extends IWaitUntil> extends Emitter<T> {

1460 >

1461 > private _asyncDeliveryQueue?: LinkedList<[(ev: T) => void, IWaitUntilData<T>]>;

1462 >

1463 > async fireAsync(data: IWaitUntilData<T>, token: CancellationToken, promiseJoin?: (p: Promise<unknown>, listener: Function) => Promise<unknown>): Promise<void> {

1464 if (!this._listeners) {

1465 return;

1512 }

1513 }

1514 > } event.ts

1515 >

1516 >

1517 > export class PauseableEmitter<T> extends Emitter<T> {

1518 >

1519 > private _isPaused = 0;

1520 > protected _eventQueue = new LinkedList<T>();

1521 > private _mergeFn?: (input: T[]) => T;

1522 >

1523 > public get isPaused(): boolean {

1524 > return this._isPaused !== 0;

1525 > }

1526 >

1527 > constructor(options?: EmitterOptions & { merge?: (input: T[]) => T }) {

1528 super(options);

1529 this._mergeFn = options?.merge;

1530 }

1531 > event.ts

1532 > pause(): void {

1533 this._isPaused++;

1534 }

1535 > event.ts

1536 > resume(): void {

1537 if (this._isPaused !== 0 && --this._isPaused === 0) {

1538 if (this._mergeFn) {

1554 }

1555 }

1556 > event.ts

1557 > override fire(event: T): void {

1558 if (this._size) {

1559 if (this._isPaused !== 0) {

1564 }

1565 }

1566 > } event.ts

1567 >

1568 > export class DebounceEmitter<T> extends PauseableEmitter<T> {

1569 >

1570 > private readonly _delay: number;

1571 > private _handle: Timeout | undefined;

1572 >

1573 > constructor(options: EmitterOptions & { merge: (input: T[]) => T; delay?: number }) {

1574 super(options);

1575 this._delay = options.delay ?? 100;

1576 }

1577 > event.ts

1578 > override fire(event: T): void {

1579 if (!this._handle) {

1580 this.pause();

1586 super.fire(event);

1587 }

1588 > } event.ts

1589 >

1590 > /**

1591 > * An emitter which queue all events and then process them at the

1592 > * end of the event loop.

1593 > */

1594 > export class MicrotaskEmitter<T> extends Emitter<T> {

1595 > private _queuedEvents: T[] = [];

1596 > private _mergeFn?: (input: T[]) => T;

1597 >

1598 > constructor(options?: EmitterOptions & { merge?: (input: T[]) => T }) {

1599 super(options);

1600 this._mergeFn = options?.merge;

1601 }

1602 > override fire(event: T): void { event.ts

1603

1604 if (!this.hasListeners()) {

1618 }

1619 }

1620 > } event.ts

1621 >

1622 > /**

1623 > * An event emitter that multiplexes many events into a single event.

1624 > *

1625 > * @example Listen to the `onData` event of all `Thing`s, dynamically adding and removing `Thing`s

1626 > * to the multiplexer as needed.

1627 > *

1628 > * ```typescript

1629 > * const anythingDataMultiplexer = new EventMultiplexer<{ data: string }>();

1630 > *

1631 > * const thingListeners = DisposableMap<Thing, IDisposable>();

1632 > *

1633 > * thingService.onDidAddThing(thing => {

1634 > * thingListeners.set(thing, anythingDataMultiplexer.add(thing.onData);

1635 > * });

1636 > * thingService.onDidRemoveThing(thing => {

1637 > * thingListeners.deleteAndDispose(thing);

1638 > * });

1639 > *

1640 > * anythingDataMultiplexer.event(e => {

1641 > * console.log('Something fired data ' + e.data)

1642 > * });

1643 > * ```

1644 > */

1645 > export class EventMultiplexer<T> implements IDisposable {

1646 >

1647 > private readonly emitter: Emitter<T>;

1648 > private hasListeners = false;

1649 > private events: { event: Event<T>; listener: IDisposable | null }[] = [];

1650 >

1651 > constructor() {

1652 this.emitter = new Emitter<T>({

1653 onWillAddFirstListener: () => this.onFirstListenerAdd(),

1655 });

1656 }

1657 > event.ts

1658 > get event(): Event<T> {

1659 return this.emitter.event;

1660 }

1661 > event.ts

1662 > add(event: Event<T>): IDisposable {

1663 const e = { event: event, listener: null };

1664 this.events.push(e);

1679 return toDisposable(createSingleCallFunction(dispose));

1680 }

1681 > event.ts

1682 > private onFirstListenerAdd(): void {

1683 this.hasListeners = true;

1684 this.events.forEach(e => this.hook(e));

1685 }

1686 > event.ts

1687 > private onLastListenerRemove(): void {

1688 this.hasListeners = false;

1689 this.events.forEach(e => this.unhook(e));

1690 }

1691 > event.ts

1692 > private hook(e: { event: Event<T>; listener: IDisposable | null }): void {

1693 e.listener = e.event(r => this.emitter.fire(r));

1694 }

1695 > event.ts

1696 > private unhook(e: { event: Event<T>; listener: IDisposable | null }): void {

1697 e.listener?.dispose();

1698 e.listener = null;

1699 }

1700 > event.ts

1701 > dispose(): void {

1702 this.emitter.dispose();

1703

1707 this.events = [];

1708 }

1709 > } event.ts

1710 >

1711 > export interface IDynamicListEventMultiplexer<TEventType> extends IDisposable {

1712 > readonly event: Event<TEventType>;

1713 > }

1714 > export class DynamicListEventMultiplexer<TItem, TEventType> implements IDynamicListEventMultiplexer<TEventType> {

1715 > private readonly _store = new DisposableStore();

1716 >

1717 > readonly event: Event<TEventType>;

1718 >

1719 > constructor(

1720 items: TItem[],

1721 onAddItem: Event<TItem>,

1747 this.event = multiplexer.event;

1748 }

1749 > event.ts

1750 > dispose() {

1751 this._store.dispose();

1752 }

1753 > } event.ts

1754 >

1755 > /**

1756 > * The EventBufferer is useful in situations in which you want

1757 > * to delay firing your events during some code.

1758 > * You can wrap that code and be sure that the event will not

1759 > * be fired during that wrap.

1760 > *

1761 > * ```

1762 > * const emitter: Emitter;

1763 > * const delayer = new EventDelayer();

1764 > * const delayedEvent = delayer.wrapEvent(emitter.event);

1765 > *

1766 > * delayedEvent(console.log);

1767 > *

1768 > * delayer.bufferEvents(() => {

1769 > * emitter.fire(); // event will not be fired yet

1770 > * });

1771 > *

1772 > * // event will only be fired at this point

1773 > * ```

1774 > */

1775 > export class EventBufferer {

1776

1777 private data: { buffers: Function[] }[] = [];

1778 > event.ts

1779 > wrapEvent<T>(event: Event<T>): Event<T>;

1780 > wrapEvent<T>(event: Event<T>, reduce: (last: T | undefined, event: T) => T): Event<T>;

1781 > wrapEvent<T, O>(event: Event<T>, reduce: (last: O | undefined, event: T) => O, initial: O): Event<O>;

1782 > wrapEvent<T, O>(event: Event<T>, reduce?: (last: T | O | undefined, event: T) => T | O, initial?: O): Event<O | T> {

1783 return (listener, thisArgs?, disposables?) => {

1784 return event(i => {

1832 };

1833 }

1834 > event.ts

1835 > bufferEvents<R = void>(fn: () => R): R {

1836 const data = { buffers: new Array<Function>() };

1837 this.data.push(data);

1841 return r;

1842 }

1843 > } event.ts

1844 >

1845 > /**

1846 > * A Relay is an event forwarder which functions as a replugabble event pipe.

1847 > * Once created, you can connect an input event to it and it will simply forward

1848 > * events from that input event through its own `event` property. The `input`

1849 > * can be changed at any point in time.

1850 > */

1851 > export class Relay<T> implements IDisposable {

1852

1853 private listening = false;

1867

1868 readonly event: Event<T> = this.emitter.event;

1869 > event.ts

1870 > set input(event: Event<T>) {

1871 this.inputEvent = event;

1872

1876 }

1877 }

1878 > event.ts

1879 > dispose() {

1880 this.inputEventListener.dispose();

1881 this.emitter.dispose();

1882 }

1883 > } event.ts

1884 >

1885 > export interface IValueWithChangeEvent<T> {

1886 > readonly onDidChange: Event<void>;

1887 > get value(): T;

1888 > }

1889 >

1890 > export class ValueWithChangeEvent<T> implements IValueWithChangeEvent<T> {

1891 > public static const<T>(value: T): IValueWithChangeEvent<T> {

1892 > return new ConstValueWithChangeEvent(value);

1893 > }

1894 >

1895 > private readonly _onDidChange = new Emitter<void>();

1896 > readonly onDidChange: Event<void> = this._onDidChange.event;

1897 >

1898 > constructor(private _value: T) { }

1899 >

1900 > get value(): T {

1901 return this._value;

1902 }

1903 > event.ts

1904 > set value(value: T) {

1905 if (value !== this._value) {

1906 this._value = value;

1908 }

1909 }

1910 > } event.ts

1911 >

1912 > class ConstValueWithChangeEvent<T> implements IValueWithChangeEvent<T> {

1913 > public readonly onDidChange: Event<void> = Event.None;

1914 >

1915 > constructor(readonly value: T) { }

1916 > }

1917 >

1918 > /**

1919 > * @param handleItem Is called for each item in the set (but only the first time the item is seen in the set).

1920 > * The returned disposable is disposed if the item is no longer in the set.

1921 > */

1922 > export function trackSetChanges<T>(getData: () => ReadonlySet<T>, onDidChangeData: Event<unknown>, handleItem: (d: T) => IDisposable): IDisposable {

1923 const map = new DisposableMap<T, IDisposable>();

1924 let oldData = new Set(getData());

1942 return store;

1943 }

1944 > event.ts

1945 >

1946 function addToDisposables(result: IDisposable, disposables: DisposableStore | IDisposable[] | undefined) {

1947 if (disposables instanceof DisposableStore) {

1951 }

1952 }

1953 > event.ts

1954 function disposeAndRemove(result: IDisposable, disposables: DisposableStore | IDisposable[] | undefined) {

1955 if (disposables instanceof DisposableStore) {