Skip to content

Commit 267b6eb

Browse files
thomas-lebeauthomas-lebeau
authored
👷 Add API surface linting for @datadog/js-core via API Extractor (#4804)
1 parent bcc2105 commit 267b6eb

14 files changed

Lines changed: 635 additions & 8 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
bundle
44
cjs
55
esm
6+
temp
67
node_modules
78
coverage
89
tunnel.log

‎.gitlab-ci.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,16 @@ check-schemas:
295295
- yarn
296296
- node scripts/check-schemas.ts
297297

298+
check-js-core-api:
299+
extends:
300+
- .base-configuration
301+
- .test-allowed-branches
302+
interruptible: true
303+
script:
304+
- yarn
305+
- yarn workspace @datadog/js-core build
306+
- yarn api:check
307+
298308
unit-bs:
299309
stage: browserstack
300310
needs: ['unit']

‎.prettierignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,8 @@ yarn.lock
1313
/developer-extension/.output
1414
/developer-extension/.wxt
1515

16+
# Auto-generated by API Extractor — do not format
17+
/packages/js-core/api
18+
1619
# Symlinks (prettier would otherwise resolve and overwrite the target file or replace the symlink with a regular file)
1720
/packages/browser-rum-slim/BROWSER_SUPPORT.md

‎LICENSE-3rdparty.csv‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ dev,@typescript-eslint/utils,MIT,Copyright (c) 2019 typescript-eslint and other
3838
dev,@wxt-dev/module-react,MIT,Copyright (c) 2023 Aaron
3939
dev,@vitejs/plugin-react,MIT,Copyright (c) 2019-present Evan You & Vite Contributors
4040
dev,@vitejs/plugin-vue,MIT,Copyright (c) 2019-present, Yuxi (Evan) You and Vite contributors
41+
dev,@microsoft/api-extractor,MIT,Copyright (c) Microsoft Corporation. All rights reserved.
4142
dev,@module-federation/enhanced,MIT, Copyright (c) 2020 ScriptedAlchemy LLC (Zack Jackson) Zhou Shaw (zhouxiao)
4243
dev,@vue/test-utils,MIT,Copyright (c) 2021-present vuejs
4344
dev,acorn,MIT,Copyright (C) 2012-2022 by various contributors (see AUTHORS)

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
],
1212
"type": "module",
1313
"scripts": {
14+
"api:check": "node scripts/check-js-core-api.ts",
1415
"build": "yarn workspaces foreach --all --parallel --topological-dev run build",
1516
"build:bundle": "yarn workspaces foreach --all --parallel run build:bundle",
1617
"build:apps": "node scripts/build/build-test-apps.ts",
@@ -45,6 +46,7 @@
4546
"@datadog/rum-events-format": "DataDog/rum-events-format#commit=02c94b31a2676458a156ed627f3edcd87254beb7",
4647
"@eslint/js": "10.0.1",
4748
"@jsdevtools/coverage-istanbul-loader": "3.0.5",
49+
"@microsoft/api-extractor": "7.58.9",
4850
"@playwright/test": "1.60.0",
4951
"@swc/core": "1.15.40",
5052
"@types/busboy": "1.5.4",

‎packages/js-core/AGENTS.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,3 +74,24 @@ When adding a new sub-path:
7474
`./packages/js-core/src/entries/<name>`
7575
5. Add `"src/entries/<name>.ts"` to the `entryPoints` array in `typedoc.json` so the sub-path
7676
appears in the generated API docs
77+
78+
### API surface linting
79+
80+
The public API surface of each sub-path is tracked via [API Extractor](https://api-extractor.com/)
81+
golden files committed to `api/*.api.md`. If you add, remove, or change any exported symbol, the
82+
check will fail and you must update the reports before merging.
83+
84+
```bash
85+
# Build the package first (API Extractor reads the compiled .d.ts files)
86+
yarn workspace @datadog/js-core build
87+
88+
# Check: verify the API surface hasn't changed (run in CI)
89+
yarn api:check
90+
91+
# Update: regenerate the golden files after an intentional API change
92+
yarn api:check --update
93+
```
94+
95+
When adding a new sub-path, build the package then run `yarn api:check --update` —
96+
`scripts/check-js-core-api.ts` discovers entry points automatically from `cjs/entries/*.d.ts`
97+
and generates the new golden file.

‎packages/js-core/api/assembly.api.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
## API Report File for "@datadog/js-core"
2+
3+
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
4+
5+
```ts
6+
7+
// @public
8+
export function createHook<Params, Result>(): Hook<Params, Result>;
9+
10+
// @public
11+
export const DISCARDED = "DISCARDED";
12+
13+
// @public (undocumented)
14+
export type DISCARDED = typeof DISCARDED;
15+
16+
// @public
17+
export interface Hook<Params, Result> {
18+
register(this: void, callback: (params: Params) => Result | DISCARDED | SKIPPED): {
19+
unregister: () => void;
20+
};
21+
trigger(this: void, params: Params): Result | DISCARDED | undefined;
22+
}
23+
24+
// @public
25+
export const SKIPPED = "SKIPPED";
26+
27+
// @public (undocumented)
28+
export type SKIPPED = typeof SKIPPED;
29+
30+
// (No @packageDocumentation comment for this package)
31+
32+
```

‎packages/js-core/api/monitor.api.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
## API Report File for "@datadog/js-core"
2+
3+
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
4+
5+
```ts
6+
7+
// @public
8+
export function createMonitor(display: Display, onMonitorErrorCollected: (error: unknown) => void): Monitor;
9+
10+
// @public
11+
export interface Monitor {
12+
callMonitored: {
13+
<T extends (...args: any[]) => unknown>(fn: T, context: ThisParameterType<T>, args: Parameters<T>): ReturnType<T> | undefined;
14+
<T extends (this: void) => unknown>(fn: T): ReturnType<T> | undefined;
15+
};
16+
monitor: <T extends (...args: any[]) => unknown>(fn: T) => T;
17+
monitored: <T extends (...params: any[]) => unknown>(_: any, __: string, descriptor: TypedPropertyDescriptor<T>) => void;
18+
monitorError: (e: unknown) => void;
19+
}
20+
21+
// (No @packageDocumentation comment for this package)
22+
23+
```

‎packages/js-core/api/time.api.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
## API Report File for "@datadog/js-core"
2+
3+
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
4+
5+
```ts
6+
7+
// @public
8+
export function addDuration(a: TimeStamp, b: Duration): TimeStamp;
9+
10+
// @public (undocumented)
11+
export function addDuration(a: RelativeTime, b: Duration): RelativeTime;
12+
13+
// @public (undocumented)
14+
export function addDuration(a: Duration, b: Duration): Duration;
15+
16+
// @public
17+
export function clockDrift(): number;
18+
19+
// @public
20+
export function clocksNow(): ClocksState;
21+
22+
// @public
23+
export function clocksOrigin(): ClocksState;
24+
25+
// @public
26+
export interface ClocksState {
27+
// (undocumented)
28+
relative: RelativeTime;
29+
// (undocumented)
30+
timeStamp: TimeStamp;
31+
}
32+
33+
// @public
34+
export function dateNow(): number;
35+
36+
// @public
37+
export type Duration = number & {
38+
d: 'Duration in ms';
39+
};
40+
41+
// @public
42+
export function elapsed(start: TimeStamp, end: TimeStamp): Duration;
43+
44+
// @public (undocumented)
45+
export function elapsed(start: RelativeTime, end: RelativeTime): Duration;
46+
47+
// @public
48+
export function getTimeOrigin(): TimeStamp;
49+
50+
// @public
51+
export function isRelativeTime(time: RelativeTime | TimeStamp): time is RelativeTime;
52+
53+
// @public
54+
export const ONE_DAY: number;
55+
56+
// @public
57+
export const ONE_HOUR: number;
58+
59+
// @public
60+
export const ONE_MINUTE: number;
61+
62+
// @public
63+
export const ONE_SECOND = 1000;
64+
65+
// @public
66+
export const ONE_YEAR: number;
67+
68+
// @public
69+
export function relativeNow(): RelativeTime;
70+
71+
// @public
72+
export type RelativeTime = number & {
73+
r: 'Time relative to navigation start';
74+
} & {
75+
d: 'Duration in ms';
76+
};
77+
78+
// @public
79+
export function relativeToClocks(relative: RelativeTime): ClocksState;
80+
81+
// @public
82+
export type ServerDuration = number & {
83+
s: 'Duration in ns';
84+
};
85+
86+
// @public
87+
export type TimeStamp = number & {
88+
t: 'Epoch time';
89+
};
90+
91+
// @public
92+
export function timeStampNow(): TimeStamp;
93+
94+
// @public
95+
export function timeStampToClocks(timeStamp: TimeStamp): ClocksState;
96+
97+
// @public
98+
export function toRelativeTime(timestamp: TimeStamp): RelativeTime;
99+
100+
// @public
101+
export function toServerDuration(duration: Duration): ServerDuration;
102+
103+
// @public (undocumented)
104+
export function toServerDuration(duration: Duration | undefined): ServerDuration | undefined;
105+
106+
// @public
107+
export function toTimeStamp(relativeTime: RelativeTime): TimeStamp;
108+
109+
// (No @packageDocumentation comment for this package)
110+
111+
```

‎packages/js-core/api/util.api.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
## API Report File for "@datadog/js-core"
2+
3+
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
4+
5+
```ts
6+
7+
// @public
8+
export function combine<A, B>(a: A, b: B): Combined<A, B>;
9+
10+
// @public (undocumented)
11+
export function combine<A, B, C>(a: A, b: B, c: C): Combined<Combined<A, B>, C>;
12+
13+
// @public (undocumented)
14+
export function combine<A, B, C, D>(a: A, b: B, c: C, d: D): Combined<Combined<Combined<A, B>, C>, D>;
15+
16+
// @public (undocumented)
17+
export function combine<A, B, C, D, E>(a: A, b: B, c: C, d: D, e: E): Combined<Combined<Combined<Combined<A, B>, C>, D>, E>;
18+
19+
// @public (undocumented)
20+
export function combine<A, B, C, D, E, F>(a: A, b: B, c: C, d: D, e: E, f: F): Combined<Combined<Combined<Combined<Combined<A, B>, C>, D>, E>, F>;
21+
22+
// @public (undocumented)
23+
export function combine<A, B, C, D, E, F, G>(a: A, b: B, c: C, d: D, e: E, f: F, g: G): Combined<Combined<Combined<Combined<Combined<Combined<A, B>, C>, D>, E>, F>, G>;
24+
25+
// @public (undocumented)
26+
export function combine<A, B, C, D, E, F, G, H>(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H): Combined<Combined<Combined<Combined<Combined<Combined<Combined<A, B>, C>, D>, E>, F>, G>, H>;
27+
28+
// @public
29+
export const ConsoleApiName: {
30+
readonly log: "log";
31+
readonly debug: "debug";
32+
readonly info: "info";
33+
readonly warn: "warn";
34+
readonly error: "error";
35+
};
36+
37+
// @public
38+
export type ConsoleApiName = (typeof ConsoleApiName)[keyof typeof ConsoleApiName];
39+
40+
// @public
41+
export function createDisplay(prefix: string): Display;
42+
43+
// @public
44+
export function deepClone<T>(value: T): T;
45+
46+
// @public
47+
export interface Display {
48+
// (undocumented)
49+
debug: typeof console.debug;
50+
// (undocumented)
51+
error: typeof console.error;
52+
// (undocumented)
53+
info: typeof console.info;
54+
// (undocumented)
55+
log: typeof console.log;
56+
// (undocumented)
57+
warn: typeof console.warn;
58+
}
59+
60+
// @public
61+
export function getDebugMode(): boolean;
62+
63+
// @public
64+
export function getType(value: unknown): "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "null" | "array";
65+
66+
// @public
67+
export const globalConsole: Console;
68+
69+
// @public
70+
export function isIndexableObject(value: unknown): value is Record<any, unknown>;
71+
72+
// @public
73+
export function mergeInto<D, S>(destination: D, source: S): Merged<D, S>;
74+
75+
// @public
76+
export const originalConsoleMethods: Display;
77+
78+
// @public
79+
export type RecursivePartial<T> = {
80+
[P in keyof T]?: T[P] extends Array<infer U> ? Array<RecursivePartial<U>> : T[P] extends object | undefined ? RecursivePartial<T[P]> : T[P];
81+
};
82+
83+
// @public
84+
export function setDebugMode(newDebugMode: boolean): void;
85+
86+
// (No @packageDocumentation comment for this package)
87+
88+
```

0 commit comments

Comments
 (0)