From b3abef0e4ec3c35a14d2c990eb0b72e51e9dc417 Mon Sep 17 00:00:00 2001 From: Neville Samuell Date: Tue, 2 Apr 2024 19:02:17 -0400 Subject: [PATCH 1/4] Build a dist/fides-types.d.ts file that includes our documented, non-internal types --- clients/fides-js/package.json | 1 + clients/fides-js/rollup.config.mjs | 17 +++++++++++++++++ clients/fides-js/src/docs/fides-event.ts | 5 +++-- clients/fides-js/src/docs/fides-options.ts | 4 ++-- clients/fides-js/src/docs/fides.ts | 22 +++++++++++----------- clients/fides-js/src/docs/index.ts | 7 +++---- clients/fides-js/tsconfig.json | 1 + 7 files changed, 38 insertions(+), 19 deletions(-) diff --git a/clients/fides-js/package.json b/clients/fides-js/package.json index ce05db8289..9e28e9e5fc 100644 --- a/clients/fides-js/package.json +++ b/clients/fides-js/package.json @@ -77,6 +77,7 @@ "typedocOptions": { "disableSources": true, "excludeExternals": true, + "excludeInternal": true, "excludePrivate": true, "githubPages": false, "hideBreadcrumbs": true, diff --git a/clients/fides-js/rollup.config.mjs b/clients/fides-js/rollup.config.mjs index 81803c2650..92a72b0454 100644 --- a/clients/fides-js/rollup.config.mjs +++ b/clients/fides-js/rollup.config.mjs @@ -114,6 +114,9 @@ const SCRIPTS = [ */ const rollupOptions = []; +/** + * For each of our entrypoint scripts, build .js, .mjs, and .d.ts outputs + */ SCRIPTS.forEach(({ name, gzipErrorSizeKb, gzipWarnSizeKb, isExtension }) => { const js = { input: `src/${name}.ts`, @@ -164,4 +167,18 @@ SCRIPTS.forEach(({ name, gzipErrorSizeKb, gzipWarnSizeKb, isExtension }) => { rollupOptions.push(...[js, mjs, declaration]); }); +/** + * In addition to our regular built outputs (like fides.js!) also generate a + * fides-types.d.ts file from our documented types for external use. + */ +rollupOptions.push({ + input: `src/docs/index.ts`, + plugins: [dts()], + output: [ + { + file: `dist/fides-types.d.ts` + }, + ] +}); + export default rollupOptions; diff --git a/clients/fides-js/src/docs/fides-event.ts b/clients/fides-js/src/docs/fides-event.ts index 5392abc79d..99cb3c08a8 100644 --- a/clients/fides-js/src/docs/fides-event.ts +++ b/clients/fides-js/src/docs/fides-event.ts @@ -2,8 +2,9 @@ * Defines the list of FidesEvent names. See {@link FidesEvent} for details on each! * * NOTE: We mark this type @private to exclude it from the generated SDK - * documentation, since it's mostly just noise - the list of events on {@link - * FidesEvent} provides a good reference. + * documentation, since it's mostly just noise there - the list of events on + * {@link FidesEvent} provides a good reference. But when coding, it's still + * useful to have this union type around! * * @private */ diff --git a/clients/fides-js/src/docs/fides-options.ts b/clients/fides-js/src/docs/fides-options.ts index 14d0b241be..ac14c7923b 100644 --- a/clients/fides-js/src/docs/fides-options.ts +++ b/clients/fides-js/src/docs/fides-options.ts @@ -97,9 +97,9 @@ export interface FidesOptions { /** * TODO (PROD-1887): Add docs for using this option. Once added, remove the - * @private tag and rebuild! + * @internal tag and rebuild! * - * @private + * @internal */ fides_primary_color: string; diff --git a/clients/fides-js/src/docs/fides.ts b/clients/fides-js/src/docs/fides.ts index b3afeed90b..3245cda30d 100644 --- a/clients/fides-js/src/docs/fides.ts +++ b/clients/fides-js/src/docs/fides.ts @@ -209,7 +209,7 @@ export interface Fides { init: (config: any) => Promise; /** - * NOTE: The properties below are all marked @private, despite being exported + * NOTE: The properties below are all marked @internal, despite being exported * on the global Fides object. This is because they are mostly implementation * details and internals that we probably *should* be hiding, to avoid * customers getting too comfortable with accessing them. @@ -217,50 +217,50 @@ export interface Fides { /** * DEFER (PROD-1815): This probably *should* be part of the documented SDK. - * - * @private + * + * @internal */ fides_meta: Record; /** * DEFER (PROD-1815): This probably *should* be part of the documented SDK. * - * @private + * @internal */ identity: Record; /** - * @private + * @internal */ experience?: any; /** - * @private + * @internal */ geolocation?: any; /** - * @private + * @internal */ options: any; /** - * @private + * @internal */ tcf_consent: any; /** - * @private + * @internal */ saved_consent: Record; /** - * @private + * @internal */ meta: (options: any) => void; /** - * @private + * @internal */ shopify: (options: any) => void; } diff --git a/clients/fides-js/src/docs/index.ts b/clients/fides-js/src/docs/index.ts index a0e69fe4ca..8a867f95e5 100644 --- a/clients/fides-js/src/docs/index.ts +++ b/clients/fides-js/src/docs/index.ts @@ -41,14 +41,13 @@ * Therefore, all the types in src/docs should be considered part of FidesJS' * *official* developer API, so treat them with care! * - * You can also use the \@private tag to intentionally leave specific - * properties/comments/etc. undocumented; this can be useful for internal-only + * You can also use the tag to intentionally leave specific + * properties/comments/etc. undocumented; this can be useful for * types for developers contributing directly to FidesJS, but that shouldn't be * included in the generic developer documentation. This comment itself is a * good example of that! - * - * @private */ + export * from "./fides"; export * from "./fides-event"; export * from "./fides-options"; \ No newline at end of file diff --git a/clients/fides-js/tsconfig.json b/clients/fides-js/tsconfig.json index 0a7a27d3c8..cb6818cbad 100644 --- a/clients/fides-js/tsconfig.json +++ b/clients/fides-js/tsconfig.json @@ -14,6 +14,7 @@ "resolveJsonModule": true, "skipLibCheck": true, "strict": true, + "stripInternal": true, "target": "es2015", "plugins": [{ "name": "typescript-plugin-css-modules" }], "baseUrl": "./", From eeae9fd9b66d64dea47c619b88560423a37f13ba Mon Sep 17 00:00:00 2001 From: Neville Samuell Date: Tue, 2 Apr 2024 19:02:59 -0400 Subject: [PATCH 2/4] Format, lint --- clients/fides-js/rollup.config.mjs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/clients/fides-js/rollup.config.mjs b/clients/fides-js/rollup.config.mjs index 92a72b0454..a59edb28de 100644 --- a/clients/fides-js/rollup.config.mjs +++ b/clients/fides-js/rollup.config.mjs @@ -176,9 +176,9 @@ rollupOptions.push({ plugins: [dts()], output: [ { - file: `dist/fides-types.d.ts` + file: `dist/fides-types.d.ts`, }, - ] + ], }); export default rollupOptions; From 3dd3e584ef85204b58f70b4dd9f0f81e3213bcf9 Mon Sep 17 00:00:00 2001 From: Neville Samuell Date: Tue, 2 Apr 2024 19:11:59 -0400 Subject: [PATCH 3/4] Fix comment --- clients/fides-js/src/docs/index.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/clients/fides-js/src/docs/index.ts b/clients/fides-js/src/docs/index.ts index 8a867f95e5..7d79fe695f 100644 --- a/clients/fides-js/src/docs/index.ts +++ b/clients/fides-js/src/docs/index.ts @@ -41,13 +41,13 @@ * Therefore, all the types in src/docs should be considered part of FidesJS' * *official* developer API, so treat them with care! * - * You can also use the tag to intentionally leave specific - * properties/comments/etc. undocumented; this can be useful for + * You can also use the "internal" tag to intentionally leave specific + * properties/comments/etc. undocumented; this can be useful for internal-only * types for developers contributing directly to FidesJS, but that shouldn't be - * included in the generic developer documentation. This comment itself is a - * good example of that! + * included in the generic developer documentation. */ +// Export all the types from files in src/docs directory export * from "./fides"; export * from "./fides-event"; export * from "./fides-options"; \ No newline at end of file From 90654944a59c3947e4f7813bd265483744afe391 Mon Sep 17 00:00:00 2001 From: Neville Samuell Date: Tue, 2 Apr 2024 19:14:37 -0400 Subject: [PATCH 4/4] Update CHANGELOG --- CHANGELOG.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a0dd90dd6..03d84bc0b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,10 +22,12 @@ The types of changes are: - Added `getModalLinkLabel` method to global fides object [#4766](https://github.com/ethyca/fides/pull/4766) ### Fixed - - Fixed select dropdowns being cut off by edges of modal forms [#4757](https://github.com/ethyca/fides/pull/4757) - Changed "allow user to dismiss" toggle to show on config form for TCF experience [#4755](https://github.com/ethyca/fides/pull/4755) +### Developer Experience +- Build a `fides-types.d.ts` type declaration file to include alongside our FidesJS developer docs [#4772](https://github.com/ethyca/fides/pull/4772) + ## [2.33.1](https://github.com/ethyca/fides/compare/2.33.0...2.33.1) ### Added