or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

alpha-apis.mdcatalog-processing.mdentity-providers.mdindex.mdlocation-conversion.mdprocessing-results.md
tile.json

tessl/npm-backstage--plugin-catalog-node

Node.js utilities and types for building Backstage catalog modules, providing core APIs for catalog processors, entity providers, and processing workflows

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@backstage/plugin-catalog-node@1.4.x

To install, run

npx @tessl/cli install tessl/npm-backstage--plugin-catalog-node@1.4.0

index.mddocs/

Backstage Plugin Catalog Node

The @backstage/plugin-catalog-node package provides essential Node.js utilities and TypeScript types for building Backstage catalog modules and extensions. It serves as the foundational library for backend catalog functionality, offering core APIs for catalog processors, entity providers, processing workflows, and utility functions for catalog operations.

Package Information

  • Package Name: @backstage/plugin-catalog-node
  • Package Type: npm
  • Language: TypeScript
  • Installation: yarn add @backstage/plugin-catalog-node

Core Imports

import {
  CatalogProcessor,
  EntityProvider,
  processingResult,
  locationSpecToLocationEntity,
  DeferredEntity
} from "@backstage/plugin-catalog-node";

For alpha features:

import {
  catalogServiceRef,
  catalogProcessingExtensionPoint
} from "@backstage/plugin-catalog-node/alpha";

Basic Usage

import {
  CatalogProcessor,
  processingResult,
  EntityProvider,
  locationSpecToLocationEntity
} from "@backstage/plugin-catalog-node";
import { Entity } from "@backstage/catalog-model";
import { LocationSpec } from "@backstage/plugin-catalog-common";

// Example processor implementation
class MyProcessor implements CatalogProcessor {
  getProcessorName(): string {
    return "my-processor";
  }

  async preProcessEntity(
    entity: Entity,
    location: LocationSpec,
    emit: CatalogProcessorEmit,
    originLocation: LocationSpec,
    cache: CatalogProcessorCache
  ): Promise<Entity> {
    // Add custom metadata
    return {
      ...entity,
      metadata: {
        ...entity.metadata,
        annotations: {
          ...entity.metadata.annotations,
          "example.com/processed": "true"
        }
      }
    };
  }
}

// Example entity provider
class MyEntityProvider implements EntityProvider {
  getProviderName(): string {
    return "my-provider";
  }

  async connect(connection: EntityProviderConnection): Promise<void> {
    // Provide entities to catalog
    await connection.applyMutation({
      type: "full",
      entities: [{ entity: myEntity }]
    });
  }
}

// Create location entity
const locationEntity = locationSpecToLocationEntity({
  location: { type: "url", target: "https://example.com/catalog.yaml" }
});

Architecture

Backstage Plugin Catalog Node is built around several key components:

  • Catalog Processors: Handle entity ingestion, transformation, and validation during catalog processing workflows
  • Entity Providers: Connect external data sources to supply entities to the catalog
  • Processing Results: Standard result types for processor operations with error handling
  • Conversion Utilities: Functions for transforming location specifications into standard formats
  • Extension Points: Alpha extension points for plugin-based architecture integration

Capabilities

Catalog Processing

Core catalog processor interface and utilities for building custom catalog processors that handle entity ingestion, transformation, and validation.

interface CatalogProcessor {
  getProcessorName(): string;
  readLocation?(
    location: LocationSpec,
    optional: boolean,
    emit: CatalogProcessorEmit,
    parser: CatalogProcessorParser,
    cache: CatalogProcessorCache
  ): Promise<boolean>;
  preProcessEntity?(
    entity: Entity,
    location: LocationSpec,
    emit: CatalogProcessorEmit,
    originLocation: LocationSpec,
    cache: CatalogProcessorCache
  ): Promise<Entity>;
  validateEntityKind?(entity: Entity): Promise<boolean>;
  postProcessEntity?(
    entity: Entity,
    location: LocationSpec,
    emit: CatalogProcessorEmit,
    cache: CatalogProcessorCache
  ): Promise<Entity>;
}

type CatalogProcessorEmit = (generated: CatalogProcessorResult) => void;

interface CatalogProcessorCache {
  get<ItemType extends JsonValue>(key: string): Promise<ItemType | undefined>;
  set<ItemType extends JsonValue>(key: string, value: ItemType): Promise<void>;
}

Catalog Processing

Entity Providers

Entity provider interface and related types for connecting external data sources to supply entities to the Backstage catalog.

interface EntityProvider {
  getProviderName(): string;
  connect(connection: EntityProviderConnection): Promise<void>;
}

interface EntityProviderConnection {
  applyMutation(mutation: EntityProviderMutation): Promise<void>;
  refresh(options: EntityProviderRefreshOptions): Promise<void>;
}

type EntityProviderMutation =
  | { type: 'full'; entities: DeferredEntity[] }
  | { type: 'delta'; added: DeferredEntity[]; removed: (DeferredEntity | { entityRef: string; locationKey?: string })[] };

Entity Providers

Processing Results

Factory functions and types for creating standardized processing results with proper error handling and result typing.

const processingResult: {
  notFoundError(atLocation: LocationSpec, message: string): CatalogProcessorResult;
  inputError(atLocation: LocationSpec, message: string): CatalogProcessorResult;
  generalError(atLocation: LocationSpec, message: string): CatalogProcessorResult;
  location(newLocation: LocationSpec): CatalogProcessorResult;
  entity(atLocation: LocationSpec, newEntity: Entity): CatalogProcessorResult;
  relation(spec: EntityRelationSpec): CatalogProcessorResult;
  refresh(key: string): CatalogProcessorResult;
};

type CatalogProcessorResult =
  | CatalogProcessorLocationResult
  | CatalogProcessorEntityResult
  | CatalogProcessorRelationResult
  | CatalogProcessorErrorResult
  | CatalogProcessorRefreshKeysResult;

Processing Results

Location Conversion

Utility functions for converting location specifications into standardized formats and Location entities.

function locationSpecToMetadataName(location: LocationSpec): string;

function locationSpecToLocationEntity(opts: {
  location: LocationSpec;
  parentEntity?: Entity;
}): LocationEntityV1alpha1;

Location Conversion

Alpha APIs

Alpha extension points and service references for plugin-based architecture integration. These APIs are in alpha stage and may change in future versions.

const catalogServiceRef: ServiceRef<CatalogApi, 'plugin'>;

interface CatalogProcessingExtensionPoint {
  addProcessor(...processors: Array<CatalogProcessor | Array<CatalogProcessor>>): void;
  addEntityProvider(...providers: Array<EntityProvider | Array<EntityProvider>>): void;
  addPlaceholderResolver(key: string, resolver: PlaceholderResolver): void;
}

const catalogProcessingExtensionPoint: ExtensionPoint<CatalogProcessingExtensionPoint>;

Alpha APIs

Processing Types

Core types and interfaces for deferred entity processing and placeholder resolution in catalog workflows.

type DeferredEntity = {
  entity: Entity;
  locationKey?: string;
};

type PlaceholderResolver = (params: PlaceholderResolverParams) => Promise<JsonValue>;

type PlaceholderResolverParams = {
  key: string;
  value: JsonValue;
  baseUrl: string;
  read: PlaceholderResolverRead;
  resolveUrl: PlaceholderResolverResolveUrl;
  emit: CatalogProcessorEmit;
};

type PlaceholderResolverRead = (url: string) => Promise<Buffer>;

type PlaceholderResolverResolveUrl = (url: string, base: string) => string;

Types

Common Types

type EntityRelationSpec = {
  source: CompoundEntityRef;
  type: string;
  target: CompoundEntityRef;
};

type LocationSpec = {
  type: string;
  target: string;
  presence?: 'required' | 'optional';
};

type CatalogProcessorParser = (options: {
  data: Buffer;
  location: LocationSpec;
}) => AsyncIterable<CatalogProcessorResult>;

Alpha Types

type ServiceRef<TService, TScope = 'root'> = {
  id: string;
  scope: TScope;
  defaultFactory?: (service: ServiceRef<TService, TScope>) => Promise<ServiceFactory<TService>>;
};

type ExtensionPoint<T> = {
  id: string;
  T: T;
};

type ServiceFactory<TService> = {
  service: ServiceRef<TService>;
  initialization: 'always' | 'lazy';
  factory: (...args: any[]) => TService | Promise<TService>;
};

type JsonValue = null | boolean | number | string | JsonArray | JsonObject;
type JsonArray = JsonValue[];
type JsonObject = { [key: string]: JsonValue };