9.3 KB407 lines
Blame
1/**
2 * This software contains information and intellectual property that is
3 * confidential and proprietary to Facebook, Inc. and its affiliates.
4 *
5 * @generated
6 */
7
8/*
9 * This file is synced between fbcode/eden/fs/facebook/prototypes/node-edenfs-notifications-client/index.d.ts.
10 * The authoritative copy is the one in eden/fs/.
11 * Use `yarn sync-edenfs-notifications` to perform the sync.
12 *
13 * This file is intended to be self contained so it may be copied/referenced from other extensions,
14 * which is why it should not import anything and why it reimplements many types.
15 */
16
17/**
18 * TypeScript type definitions for EdenFS Notifications Client
19 * JavaScript interface for EdenFS CLI notify endpoint
20 */
21
22import {EventEmitter} from 'events';
23
24/**
25 * Options for initializing EdenFSNotificationsClient
26 */
27export interface EdenFSClientOptions {
28 /** Path to the mount point */
29 mountPoint?: string;
30 /** Timeout in milliseconds for commands (default: 30000) */
31 timeout?: number;
32 /** Path to the eden binary (default: 'eden') */
33 edenBinaryPath?: string;
34}
35
36/**
37 * Journal position information
38 */
39export interface JournalPosition {
40 journalPosition: string;
41}
42
43/**
44 * Options for getStatus command
45 */
46export interface GetStatusOptions {
47 /** Use case identifier for the command */
48 useCase?: string;
49}
50
51/**
52 * Options for waitReady command
53 */
54export interface WaitReadyOptions {
55 /** Use case identifier for the command */
56 useCase?: string;
57 /** Timeout in milliseconds for the command (overrides constructor value) */
58 timeout?: number;
59}
60
61/**
62 * Options for getPosition command
63 */
64export interface GetPositionOptions {
65 /** Use case identifier for the command */
66 useCase?: string;
67 /** Mount point path (overrides constructor value) */
68 mountPoint?: string;
69}
70
71/**
72 * Options for getChangesSince command
73 */
74export interface GetChangesSinceOptions {
75 /** Journal position to start from */
76 position?: string | JournalPosition;
77 /** Use case identifier */
78 useCase?: string;
79 /** Mount point path (overrides constructor value) */
80 mountPoint?: string;
81 /** Relative root to scope results */
82 relativeRoot?: string;
83 /** Include VCS roots in output */
84 includeVcsRoots?: boolean;
85 /** Included roots in output */
86 includedRoots?: string[];
87 /** Excluded roots in output */
88 excludedRoots?: string[];
89 /** Included file suffixes in output */
90 includedSuffixes?: string[];
91 /** Excluded file suffixes in output */
92 excludedSuffixes?: string[];
93 /** Return JSON format (default: true) */
94 json?: boolean;
95 /** States to wait for deassertion */
96 deferredStates?: string[];
97}
98
99/**
100 * Options for subscription
101 */
102export interface SubscriptionOptions {
103 /** Journal position to start from */
104 position?: string;
105 /** Use case identifier */
106 useCase?: string;
107 /** Mount point path */
108 mountPoint?: string;
109 /** Throttle in milliseconds between events (default: 0) */
110 throttle?: number;
111 /** Relative root to scope results */
112 relativeRoot?: string;
113 /** Include VCS roots in output */
114 includeVcsRoots?: boolean;
115 /** Included roots in output */
116 includedRoots?: string[];
117 /** Excluded roots in output */
118 excludedRoots?: string[];
119 /** Included file suffixes in output */
120 includedSuffixes?: string[];
121 /** Excluded file suffixes in output */
122 excludedSuffixes?: string[];
123 /** States to wait for deassertion */
124 deferredStates?: string[];
125 /** Path to eden binary */
126 edenBinaryPath?: string;
127}
128
129/**
130 * Options for enterState command
131 */
132export interface EnterStateOptions {
133 /** Duration in seconds to maintain state */
134 duration?: number;
135 /** Use case identifier */
136 useCase?: string;
137 /** Mount point path (overrides constructor value) */
138 mountPoint?: string;
139}
140
141/**
142 * Small change types
143 */
144export interface AddedChange {
145 path: number[];
146 file_type: string;
147}
148
149export interface ModifiedChange {
150 path: number[];
151 file_type: string;
152}
153
154export interface RemovedChange {
155 path: number[];
156 file_type: string;
157}
158
159export interface RenamedChange {
160 from: number[];
161 to: number[];
162 file_type: string;
163}
164
165export interface ReplacedChange {
166 from: number[];
167 to: number[];
168 file_type: string;
169}
170
171export interface SmallChange {
172 Added?: AddedChange;
173 Modified?: ModifiedChange;
174 Removed?: RemovedChange;
175 Renamed?: RenamedChange;
176 Replaced?: ReplacedChange;
177}
178
179/**
180 * Large change types
181 */
182export interface DirectoryRenamedChange {
183 from: number[];
184 to: number[];
185}
186
187export interface CommitTransitionChange {
188 from: number[];
189 to: number[];
190}
191
192export interface LostChanges {
193 reason: string;
194}
195
196export interface LargeChange {
197 DirectoryRenamed?: DirectoryRenamedChange;
198 CommitTransition?: CommitTransitionChange;
199 LostChanges?: LostChanges;
200}
201
202/**
203 * State change types
204 */
205export interface StateEnteredChange {
206 state: string;
207}
208
209export interface StateLeftChange {
210 state: string;
211}
212
213export interface StateChange {
214 StateEntered?: StateEnteredChange;
215 StateLeft?: StateLeftChange;
216}
217
218/**
219 * File system change event
220 */
221export interface Change {
222 SmallChange?: SmallChange;
223 LargeChange?: LargeChange;
224 StateChange?: StateChange;
225}
226
227/**
228 * Response from getChangesSince
229 */
230export interface ChangesSinceResponse {
231 /** List of changes */
232 changes: Change[];
233 /** New journal position after changes */
234 to_position?: string;
235}
236
237/**
238 * Event emitted by subscription
239 */
240export interface SubscriptionEvent extends ChangesSinceResponse {
241 /** Position a state change occurred at */
242 position?: string;
243 /** Event type for state changes */
244 event_type?: 'Entered' | 'Left';
245 /** State name for state change events */
246 state?: string;
247}
248
249/**
250 * Callback for subscription events
251 */
252export type SubscriptionCallback = (error: Error | null, result: SubscriptionEvent | null) => void;
253
254/**
255 * Custom error class for EdenFS errors
256 */
257export class EdenFSError extends Error {
258 edenFSResponse: any;
259}
260
261/**
262 * EdenFS Notifications Client
263 * Provides methods to interact with EdenFS notifications via the EdenFS CLI
264 */
265export class EdenFSNotificationsClient extends EventEmitter {
266 mountPoint: string | null;
267 timeout: number;
268 edenBinaryPath: string;
269 readonly DEFAULT_EDENFS_RECONNECT_DELAY_MS: number;
270 readonly MAXIMUM_EDENFS_RECONNECT_DELAY_MS: number;
271
272 constructor(options?: EdenFSClientOptions);
273
274 /**
275 * Get the current EdenFS status
276 */
277 getStatus(options?: GetStatusOptions): Promise<string>;
278
279 /**
280 * Wait until EdenFS is ready, using getStatus
281 * @returns Promise that resolves to true if healthy, false if timeout
282 */
283 waitReady(options?: WaitReadyOptions): Promise<boolean>;
284
285 /**
286 * Get the current EdenFS journal position
287 */
288 getPosition(options?: GetPositionOptions): Promise<string>;
289
290 /**
291 * Get changes since a specific journal position
292 */
293 getChangesSince(options?: GetChangesSinceOptions): Promise<ChangesSinceResponse>;
294
295 /**
296 * Subscribe to filesystem changes
297 */
298 subscribe(options?: SubscriptionOptions, callback?: SubscriptionCallback): EdenFSSubscription;
299
300 /**
301 * Enter a specific state
302 */
303 enterState(state: string, options?: EnterStateOptions): Promise<void>;
304}
305
306/**
307 * EdenFS Subscription
308 * Handles real-time filesystem change notifications
309 */
310export class EdenFSSubscription extends EventEmitter {
311 client: EdenFSNotificationsClient;
312 options: SubscriptionOptions;
313 process: any;
314 edenBinaryPath: string;
315 errData: string;
316 killTimeout: NodeJS.Timeout | null;
317
318 constructor(client: EdenFSNotificationsClient, options?: SubscriptionOptions);
319
320 /**
321 * Start the subscription
322 */
323 start(): Promise<void>;
324
325 /**
326 * Stop the subscription
327 */
328 stop(): void;
329
330 // EventEmitter events
331 on(event: 'change', listener: (event: SubscriptionEvent) => void): this;
332 on(event: 'error', listener: (error: Error) => void): this;
333 on(event: 'close', listener: () => void): this;
334
335 once(event: 'change', listener: (event: SubscriptionEvent) => void): this;
336 once(event: 'error', listener: (error: Error) => void): this;
337 once(event: 'close', listener: () => void): this;
338
339 emit(event: 'change', data: SubscriptionEvent): boolean;
340 emit(event: 'error', error: Error): boolean;
341 emit(event: 'close'): boolean;
342}
343
344/**
345 * Utility functions for working with EdenFS notify data
346 */
347export class EdenFSUtils {
348 /**
349 * Convert byte array path to string
350 */
351 static bytesToPath(pathBytes: number[]): string;
352
353 /**
354 * Convert byte array to hex string
355 */
356 static bytesToHex(bytes: number[]): string;
357
358 /**
359 * Extract file type from change
360 */
361 static extractFileType(smallChange: SmallChange): string;
362
363 /**
364 * Extract file path(s) from single change
365 */
366 static extractPath(changes: SmallChange): string[];
367
368 /**
369 * Extract file paths from changes
370 */
371 static extractPaths(changes: Change[]): string[];
372
373 /**
374 * Get change type from a change object
375 */
376 static getChangeType(
377 change: Change,
378 ):
379 | 'added'
380 | 'modified'
381 | 'removed'
382 | 'renamed'
383 | 'replaced'
384 | 'directory renamed'
385 | 'commit transition'
386 | 'lost changes'
387 | 'state entered'
388 | 'state left'
389 | 'unknown';
390}
391
392declare const exports: {
393 EdenFSNotificationsClient: typeof EdenFSNotificationsClient;
394 EdenFSSubscription: typeof EdenFSSubscription;
395 EdenFSUtils: typeof EdenFSUtils;
396};
397
398export default exports;
399
400export type Options = {
401 mountPoint?: string;
402 timeout?: number;
403 edenBinaryPath?: string;
404};
405
406export type CommandCallback = (error?: Error, result?: Response) => void;
407