@backstage/plugin-catalog-node 1.16.2 → 1.16.3

package/CHANGELOG.md

@@ -1,10 +1,26 @@
 # @backstage/plugin-catalog-node
 
-## 1.16.2
+## 1.16.3
 
 ### Patch Changes
 
-- 0faff9f: Use a different ID for the deprecated alpha version of the catalog service, as it has a different type definition and cannot be used interchangeably with the non-alpha version.
+- 2c5598c: Adds documentation for the CatalogProcessingExtensionPoint functions.
+- 98b7131: Use a different ID for the deprecated alpha version of the catalog service, as it has a different type definition and cannot be used interchangeably with the non-alpha version.
+- Updated dependencies
+  - @backstage/backend-plugin-api@1.3.0
+  - @backstage/plugin-permission-node@0.9.1
+  - @backstage/catalog-client@1.9.1
+  - @backstage/catalog-model@1.7.3
+  - @backstage/errors@1.2.7
+  - @backstage/types@1.2.1
+  - @backstage/plugin-catalog-common@1.1.3
+  - @backstage/plugin-permission-common@0.8.4
+
+## 1.16.3-next.0
+
+### Patch Changes
+
+- 98b7131: Use a different ID for the deprecated alpha version of the catalog service, as it has a different type definition and cannot be used interchangeably with the non-alpha version.
 - Updated dependencies
   - @backstage/backend-plugin-api@1.2.1
   - @backstage/catalog-client@1.9.1

package/dist/alpha.d.ts

@@ -24,8 +24,33 @@ declare const catalogLocationsExtensionPoint: _backstage_backend_plugin_api.Exte
  * @alpha
  */
 interface CatalogProcessingExtensionPoint {
+    /**
+     * Adds entity processors. These are responsible for reading, parsing, and
+     * processing entities before they are persisted in the catalog.
+     *
+     * This function also can replace a Default processor if the provided processor
+     * matches the processor name.
+     *
+     * @param processors - One or more processors
+     */
     addProcessor(...processors: Array<CatalogProcessor | Array<CatalogProcessor>>): void;
+    /**
+     * Adds or replaces entity providers. These are responsible for bootstrapping
+     * the list of entities out of original data sources. For example, there is
+     * one entity source for the config locations, and one for the database
+     * stored locations. If you ingest entities out of a third party system, you
+     * may want to implement that in terms of an entity provider as well.
+     *
+     * @param providers - One or more entity providers
+     */
     addEntityProvider(...providers: Array<EntityProvider | Array<EntityProvider>>): void;
+    /**
+     * Adds, or overwrites, a handler for placeholders (e.g. $file) in entity
+     * definition files.
+     *
+     * @param key - The key that identifies the placeholder, e.g. "file"
+     * @param resolver - The resolver that gets values for this placeholder
+     */
     addPlaceholderResolver(key: string, resolver: PlaceholderResolver): void;
     setOnProcessingErrorHandler(handler: (event: {
         unprocessedEntity: Entity;

package/dist/extensions.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"extensions.cjs.js","sources":["../src/extensions.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createExtensionPoint } from '@backstage/backend-plugin-api';\nimport { Entity, Validators } from '@backstage/catalog-model';\nimport {\n  CatalogProcessor,\n  CatalogProcessorParser,\n  EntitiesSearchFilter,\n  EntityProvider,\n  PlaceholderResolver,\n  LocationAnalyzer,\n  ScmLocationAnalyzer,\n} from '@backstage/plugin-catalog-node';\nimport {\n  Permission,\n  PermissionRuleParams,\n} from '@backstage/plugin-permission-common';\nimport { PermissionRule } from '@backstage/plugin-permission-node';\n\n/**\n * @alpha\n */\nexport interface CatalogLocationsExtensionPoint {\n  /**\n   * Allows setting custom location types, such as showcased in: https://backstage.io/docs/features/software-catalog/external-integrations/#creating-a-catalog-data-reader-processor\n   * @param locationTypes - List of location types to allow, default is \"url\" and \"file\"\n   */\n  setAllowedLocationTypes(locationTypes: Array<string>): void;\n}\n\n/**\n * @alpha\n */\nexport const catalogLocationsExtensionPoint =\n  createExtensionPoint<CatalogLocationsExtensionPoint>({\n    id: 'catalog.locations',\n  });\n\n/**\n * @alpha\n */\nexport interface CatalogProcessingExtensionPoint {\n  addProcessor(\n    ...processors: Array<CatalogProcessor | Array<CatalogProcessor>>\n  ): void;\n  addEntityProvider(\n    ...providers: Array<EntityProvider | Array<EntityProvider>>\n  ): void;\n  addPlaceholderResolver(key: string, resolver: PlaceholderResolver): void;\n  setOnProcessingErrorHandler(\n    handler: (event: {\n      unprocessedEntity: Entity;\n      errors: Error[];\n    }) => Promise<void> | void,\n  ): void;\n}\n\n/** @alpha */\nexport interface CatalogModelExtensionPoint {\n  /**\n   * Sets the validator function to use for one or more special fields of an\n   * entity. This is useful if the default rules for formatting of fields are\n   * not sufficient.\n   *\n   * @param validators - The (subset of) validators to set\n   */\n  setFieldValidators(validators: Partial<Validators>): void;\n\n  /**\n   * Sets the entity data parser which is used to read raw data from locations\n   * @param parser - Parser which will used to extract entities from raw data\n   */\n  setEntityDataParser(parser: CatalogProcessorParser): void;\n}\n\n/**\n * @alpha\n */\nexport const catalogProcessingExtensionPoint =\n  createExtensionPoint<CatalogProcessingExtensionPoint>({\n    id: 'catalog.processing',\n  });\n\n/**\n * @alpha\n */\nexport interface CatalogAnalysisExtensionPoint {\n  /**\n   * Replaces the entire location analyzer with a new one.\n   *\n   * @remarks\n   *\n   * By providing a factory function you can access all the SCM analyzers that\n   * have been added through `addScmLocationAnalyzer`. If you provide a\n   * `LocationAnalyzer` directly, the SCM analyzers will be ignored.\n   */\n  setLocationAnalyzer(\n    analyzerOrFactory:\n      | LocationAnalyzer\n      | ((options: {\n          scmLocationAnalyzers: ScmLocationAnalyzer[];\n        }) => Promise<{ locationAnalyzer: LocationAnalyzer }>),\n  ): void;\n\n  /**\n   * Adds an analyzer for a specific SCM type to the default location analyzer.\n   */\n  addScmLocationAnalyzer(analyzer: ScmLocationAnalyzer): void;\n}\n\n/**\n * @alpha\n */\nexport const catalogAnalysisExtensionPoint =\n  createExtensionPoint<CatalogAnalysisExtensionPoint>({\n    id: 'catalog.analysis',\n  });\n\n/** @alpha */\nexport const catalogModelExtensionPoint =\n  createExtensionPoint<CatalogModelExtensionPoint>({\n    id: 'catalog.model',\n  });\n\n/**\n * @alpha\n * @deprecated Use the `coreServices.permissionsRegistry` instead.\n */\nexport type CatalogPermissionRuleInput<\n  TParams extends PermissionRuleParams = PermissionRuleParams,\n> = PermissionRule<Entity, EntitiesSearchFilter, 'catalog-entity', TParams>;\n\n/**\n * @alpha\n * @deprecated Use the `coreServices.permissionsRegistry` instead.\n */\nexport interface CatalogPermissionExtensionPoint {\n  addPermissions(...permissions: Array<Permission | Array<Permission>>): void;\n  addPermissionRules(\n    ...rules: Array<\n      CatalogPermissionRuleInput | Array<CatalogPermissionRuleInput>\n    >\n  ): void;\n}\n\n/**\n * @alpha\n * @deprecated Use the `coreServices.permissionsRegistry` instead.\n */\nexport const catalogPermissionExtensionPoint =\n  createExtensionPoint<CatalogPermissionExtensionPoint>({\n    id: 'catalog.permission',\n  });\n"],"names":["createExtensionPoint"],"mappings":";;;;AA+CO,MAAM,iCACXA,qCAAqD,CAAA;AAAA,EACnD,EAAI,EAAA;AACN,CAAC;AA0CI,MAAM,kCACXA,qCAAsD,CAAA;AAAA,EACpD,EAAI,EAAA;AACN,CAAC;AAgCI,MAAM,gCACXA,qCAAoD,CAAA;AAAA,EAClD,EAAI,EAAA;AACN,CAAC;AAGI,MAAM,6BACXA,qCAAiD,CAAA;AAAA,EAC/C,EAAI,EAAA;AACN,CAAC;AA2BI,MAAM,kCACXA,qCAAsD,CAAA;AAAA,EACpD,EAAI,EAAA;AACN,CAAC;;;;;;;;"}
+{"version":3,"file":"extensions.cjs.js","sources":["../src/extensions.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createExtensionPoint } from '@backstage/backend-plugin-api';\nimport { Entity, Validators } from '@backstage/catalog-model';\nimport {\n  CatalogProcessor,\n  CatalogProcessorParser,\n  EntitiesSearchFilter,\n  EntityProvider,\n  PlaceholderResolver,\n  LocationAnalyzer,\n  ScmLocationAnalyzer,\n} from '@backstage/plugin-catalog-node';\nimport {\n  Permission,\n  PermissionRuleParams,\n} from '@backstage/plugin-permission-common';\nimport { PermissionRule } from '@backstage/plugin-permission-node';\n\n/**\n * @alpha\n */\nexport interface CatalogLocationsExtensionPoint {\n  /**\n   * Allows setting custom location types, such as showcased in: https://backstage.io/docs/features/software-catalog/external-integrations/#creating-a-catalog-data-reader-processor\n   * @param locationTypes - List of location types to allow, default is \"url\" and \"file\"\n   */\n  setAllowedLocationTypes(locationTypes: Array<string>): void;\n}\n\n/**\n * @alpha\n */\nexport const catalogLocationsExtensionPoint =\n  createExtensionPoint<CatalogLocationsExtensionPoint>({\n    id: 'catalog.locations',\n  });\n\n/**\n * @alpha\n */\nexport interface CatalogProcessingExtensionPoint {\n  /**\n   * Adds entity processors. These are responsible for reading, parsing, and\n   * processing entities before they are persisted in the catalog.\n   *\n   * This function also can replace a Default processor if the provided processor\n   * matches the processor name.\n   *\n   * @param processors - One or more processors\n   */\n  addProcessor(\n    ...processors: Array<CatalogProcessor | Array<CatalogProcessor>>\n  ): void;\n\n  /**\n   * Adds or replaces entity providers. These are responsible for bootstrapping\n   * the list of entities out of original data sources. For example, there is\n   * one entity source for the config locations, and one for the database\n   * stored locations. If you ingest entities out of a third party system, you\n   * may want to implement that in terms of an entity provider as well.\n   *\n   * @param providers - One or more entity providers\n   */\n  addEntityProvider(\n    ...providers: Array<EntityProvider | Array<EntityProvider>>\n  ): void;\n\n  /**\n   * Adds, or overwrites, a handler for placeholders (e.g. $file) in entity\n   * definition files.\n   *\n   * @param key - The key that identifies the placeholder, e.g. \"file\"\n   * @param resolver - The resolver that gets values for this placeholder\n   */\n  addPlaceholderResolver(key: string, resolver: PlaceholderResolver): void;\n\n  setOnProcessingErrorHandler(\n    handler: (event: {\n      unprocessedEntity: Entity;\n      errors: Error[];\n    }) => Promise<void> | void,\n  ): void;\n}\n\n/** @alpha */\nexport interface CatalogModelExtensionPoint {\n  /**\n   * Sets the validator function to use for one or more special fields of an\n   * entity. This is useful if the default rules for formatting of fields are\n   * not sufficient.\n   *\n   * @param validators - The (subset of) validators to set\n   */\n  setFieldValidators(validators: Partial<Validators>): void;\n\n  /**\n   * Sets the entity data parser which is used to read raw data from locations\n   * @param parser - Parser which will used to extract entities from raw data\n   */\n  setEntityDataParser(parser: CatalogProcessorParser): void;\n}\n\n/**\n * @alpha\n */\nexport const catalogProcessingExtensionPoint =\n  createExtensionPoint<CatalogProcessingExtensionPoint>({\n    id: 'catalog.processing',\n  });\n\n/**\n * @alpha\n */\nexport interface CatalogAnalysisExtensionPoint {\n  /**\n   * Replaces the entire location analyzer with a new one.\n   *\n   * @remarks\n   *\n   * By providing a factory function you can access all the SCM analyzers that\n   * have been added through `addScmLocationAnalyzer`. If you provide a\n   * `LocationAnalyzer` directly, the SCM analyzers will be ignored.\n   */\n  setLocationAnalyzer(\n    analyzerOrFactory:\n      | LocationAnalyzer\n      | ((options: {\n          scmLocationAnalyzers: ScmLocationAnalyzer[];\n        }) => Promise<{ locationAnalyzer: LocationAnalyzer }>),\n  ): void;\n\n  /**\n   * Adds an analyzer for a specific SCM type to the default location analyzer.\n   */\n  addScmLocationAnalyzer(analyzer: ScmLocationAnalyzer): void;\n}\n\n/**\n * @alpha\n */\nexport const catalogAnalysisExtensionPoint =\n  createExtensionPoint<CatalogAnalysisExtensionPoint>({\n    id: 'catalog.analysis',\n  });\n\n/** @alpha */\nexport const catalogModelExtensionPoint =\n  createExtensionPoint<CatalogModelExtensionPoint>({\n    id: 'catalog.model',\n  });\n\n/**\n * @alpha\n * @deprecated Use the `coreServices.permissionsRegistry` instead.\n */\nexport type CatalogPermissionRuleInput<\n  TParams extends PermissionRuleParams = PermissionRuleParams,\n> = PermissionRule<Entity, EntitiesSearchFilter, 'catalog-entity', TParams>;\n\n/**\n * @alpha\n * @deprecated Use the `coreServices.permissionsRegistry` instead.\n */\nexport interface CatalogPermissionExtensionPoint {\n  addPermissions(...permissions: Array<Permission | Array<Permission>>): void;\n  addPermissionRules(\n    ...rules: Array<\n      CatalogPermissionRuleInput | Array<CatalogPermissionRuleInput>\n    >\n  ): void;\n}\n\n/**\n * @alpha\n * @deprecated Use the `coreServices.permissionsRegistry` instead.\n */\nexport const catalogPermissionExtensionPoint =\n  createExtensionPoint<CatalogPermissionExtensionPoint>({\n    id: 'catalog.permission',\n  });\n"],"names":["createExtensionPoint"],"mappings":";;;;AA+CO,MAAM,iCACXA,qCAAqD,CAAA;AAAA,EACnD,EAAI,EAAA;AACN,CAAC;AAsEI,MAAM,kCACXA,qCAAsD,CAAA;AAAA,EACpD,EAAI,EAAA;AACN,CAAC;AAgCI,MAAM,gCACXA,qCAAoD,CAAA;AAAA,EAClD,EAAI,EAAA;AACN,CAAC;AAGI,MAAM,6BACXA,qCAAiD,CAAA;AAAA,EAC/C,EAAI,EAAA;AACN,CAAC;AA2BI,MAAM,kCACXA,qCAAsD,CAAA;AAAA,EACpD,EAAI,EAAA;AACN,CAAC;;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-catalog-node",
-  "version": "1.16.2",
+  "version": "1.16.3",
   "description": "The plugin-catalog-node module for @backstage/plugin-catalog-backend",
   "backstage": {
     "role": "node-library",
@@ -48,14 +48,14 @@
   "types": "./dist/index.d.ts",
   "typesVersions": {
     "*": {
-      "*": [
-        "dist/index.d.ts"
-      ],
       "alpha": [
         "dist/alpha.d.ts"
       ],
       "testUtils": [
         "dist/testUtils.d.ts"
+      ],
+      "package.json": [
+        "package.json"
       ]
     }
   },
@@ -72,18 +72,18 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/backend-plugin-api": "^1.2.1",
+    "@backstage/backend-plugin-api": "^1.3.0",
     "@backstage/catalog-client": "^1.9.1",
     "@backstage/catalog-model": "^1.7.3",
     "@backstage/errors": "^1.2.7",
     "@backstage/plugin-catalog-common": "^1.1.3",
     "@backstage/plugin-permission-common": "^0.8.4",
-    "@backstage/plugin-permission-node": "^0.9.0",
+    "@backstage/plugin-permission-node": "^0.9.1",
     "@backstage/types": "^1.2.1"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "^1.3.1",
-    "@backstage/cli": "^0.31.1",
+    "@backstage/backend-test-utils": "^1.4.0",
+    "@backstage/cli": "^0.32.0",
     "msw": "^1.0.0"
   }
 }