catalog.json

{
  "version": 1,
  "groups": {
    "tracing": {
      "title": "Tracing / APM",
      "exclusive": true,
      "pick": "Only if the service is traced — none is normal."
    },
    "orm": {
      "title": "ORM / database",
      "exclusive": true,
      "pick": "Only if the service uses a database — none is normal."
    },
    "features": { "title": "Service features", "exclusive": false }
  },
  "packages": {
    "opentelemetry": {
      "group": "tracing",
      "title": "OpenTelemetry instrumentation",
      "pick": "Recommended: vendor-neutral, so the backend can change without touching service code.",
      "deps": {
        "@imqueue/opentelemetry": "*",
        "@opentelemetry/api": "*",
        "@opentelemetry/instrumentation": "*",
        "@opentelemetry/resources": "*",
        "@opentelemetry/sdk-trace-node": "*",
        "@opentelemetry/semantic-conventions": "*"
      },
      "snippets": { "preload": "import './telemetry.js';" },
      "env": ["OTEL_EXPORTER_OTLP_ENDPOINT"],
      "instructions": [
        "OpenTelemetry: tracing is initialized in src/telemetry.ts (imported first at start-up).",
        "OpenTelemetry: add the 'gcp' package to export traces to Google Cloud Trace."
      ]
    },
    "gcp": {
      "group": "features",
      "title": "Google Cloud Trace exporter (for OpenTelemetry)",
      "deps": { "@google-cloud/opentelemetry-cloud-trace-exporter": "*" },
      "env": ["GOOGLE_APPLICATION_CREDENTIALS"],
      "instructions": [
        "GCP trace export: requires the opentelemetry package; traces export to Google Cloud Trace when GOOGLE_APPLICATION_CREDENTIALS is set."
      ]
    },
    "dd-trace": {
      "group": "tracing",
      "title": "Datadog APM",
      "hint": "already on Datadog",
      "pick": "For a fleet already standing on Datadog\u2019s own agent; otherwise take opentelemetry.",
      "deps": { "@imqueue/datadog": "*" },
      "snippets": { "preload": "import './tracer.js';" },
      "env": ["DD_AGENT_HOST", "DD_TRACE_ENABLED"],
      "instructions": [
        "Datadog: tracing is initialized in src/tracer.ts (imported first at start-up).",
        "Datadog: ensure a Datadog agent is reachable via DD_AGENT_HOST."
      ]
    },
    "sequelize": {
      "group": "orm",
      "title": "Sequelize ORM + @imqueue/pg-sequelize toolkit",
      "hint": "match a Sequelize fleet",
      "pick": "For a service joining a fleet already built on Sequelize, where matching the existing stack is worth more than the default. Migrating the fleet to pg-prisma is worth proposing, as separate work.",
      "deps": { "@imqueue/pg-sequelize": "*", "sequelize": "*" },
      "instructions": [
        "Sequelize: configure your database connection in config.ts."
      ]
    },
    "pg-prisma": {
      "group": "orm",
      "title": "Prisma ORM + @imqueue/pg-prisma toolkit",
      "pick": "Recommended. Take this unless the fleet the service joins is already built on Sequelize.",
      "deps": {
        "@imqueue/pg-prisma": "*",
        "@imqueue/validation": "*",
        "@prisma/client": "*",
        "@prisma/adapter-pg": "*",
        "pg": "*",
        "zod": "*"
      },
      "devDeps": { "prisma": "*", "@types/pg": "*" },
      "env": ["DATABASE_URL"],
      "instructions": [
        "pg-prisma: set DATABASE_URL, then run `npx prisma migrate dev` to create the database.",
        "pg-prisma: edit prisma/schema.prisma and run `npx prisma generate` to (re)generate models."
      ]
    },
    "validation": {
      "group": "features",
      "title": "Input validation (@imqueue/validation)",
      "deps": { "@imqueue/validation": "*", "zod": "*" },
      "instructions": [
        "validation: annotate argument classes with @validatable/@validate and methods with @validated."
      ]
    },
    "core": {
      "group": "features",
      "title": "@imqueue/core (direct dependency)",
      "deps": { "@imqueue/core": "*" },
      "instructions": [
        "core: @imqueue/core is otherwise pulled in transitively by @imqueue/rpc; add it directly only if you import from it."
      ]
    },
    "pg-cache": {
      "group": "features",
      "title": "PostgreSQL query cache",
      "deps": { "@imqueue/pg-cache": "*" }
    },
    "pg-pubsub": {
      "group": "features",
      "title": "PostgreSQL pub/sub",
      "deps": { "@imqueue/pg-pubsub": "*" }
    },
    "tag-cache": {
      "group": "features",
      "title": "Tag-based cache",
      "deps": { "@imqueue/tag-cache": "*" }
    },
    "job": {
      "group": "features",
      "title": "Background jobs",
      "deps": { "@imqueue/job": "*" }
    },
    "net": {
      "group": "features",
      "title": "Network helpers",
      "deps": { "@imqueue/net": "*" }
    },
    "http-protect": {
      "group": "features",
      "title": "HTTP protection",
      "deps": { "@imqueue/http-protect": "*" }
    },
    "graphql-dependency": {
      "group": "features",
      "title": "GraphQL dependency resolution",
      "deps": { "@imqueue/graphql-dependency": "*" }
    },
    "type-graphql-dependency": {
      "group": "features",
      "title": "TypeGraphQL dependency resolution",
      "deps": { "@imqueue/type-graphql-dependency": "*" }
    }
  }
}