sellyguide-common

SellyGuide mikroservis mimarisinde tüm servislerin paylaştığı ortak paket.

Dual-build desteği: Hem CommonJS (require) hem ESM (import) tüketicileri desteklenir.

İçerik

• DTO: Ortak veri transfer nesneleri ve Zod şemaları
• Logger: Pino tabanlı yapılandırılabilir loglama
• Config: Zod ile doğrulanmış ortam değişkenleri (loadEnv())
• Errors: Standart hata sınıfları (AppError, HTTP hataları)
• Kafka: Event publisher ve consumer altyapısı
• Events: Standartlaştırılmış event zarfı ve örnek eventler
• Utils: Yardımcı fonksiyonlar (id, timestamp)

Kurulum

npm install sellyguide-common
# veya
pnpm add sellyguide-common

Önemli: zod paketini de kurmanız gerekiyor (peer dependency):

pnpm add zod

Kullanım

.env Yükleme

Paket .env yüklemez. Uygulama tarafından yüklenmelidir:

// ESM
import "dotenv/config";
// veya
// CommonJS
require("dotenv/config");

Config

// ESM
import "dotenv/config";
import { loadEnv } from "sellyguide-common/config/env";

const env = loadEnv();
console.log(env.KAFKA_BROKERS_LIST);

// CommonJS
require("dotenv/config");
const { loadEnv } = require("sellyguide-common/config/env");

const env = loadEnv();
console.log(env.KAFKA_BROKERS_LIST);

Subpath Exports

Subpath exports kullanarak daha iyi tree-shaking ve bundle size:

// ESM
import { NotFoundError } from "sellyguide-common/errors/http-errors";
import { EventPublisher } from "sellyguide-common/kafka";
import { logger } from "sellyguide-common/logger/logger";
import { loadEnv } from "sellyguide-common/config/env";

// CommonJS
const { NotFoundError } = require("sellyguide-common/errors/http-errors");
const { EventPublisher } = require("sellyguide-common/kafka");
const { logger } = require("sellyguide-common/logger/logger");
const { loadEnv } = require("sellyguide-common/config/env");

Logger

import { logger, withReqId } from "sellyguide-common/logger/logger";

logger.info({ userId: "123" }, "User action completed");
const reqLogger = withReqId("req-456");
reqLogger.info("Request processed");

Errors

import { NotFoundError, BadRequestError } from "sellyguide-common/errors/http-errors";

throw new NotFoundError("User not found");
throw new BadRequestError("Invalid input", { field: "email" });

Kafka Event Publishing

import { EventPublisher } from "sellyguide-common/kafka";
import { USER_CREATED, USER_CREATED_TOPIC } from "sellyguide-common/events";
import { nowIso, randomId } from "sellyguide-common/utils";

const publisher = new EventPublisher("user-service");

await publisher.publish(USER_CREATED_TOPIC, {
  id: randomId(),
  type: USER_CREATED.type,
  version: USER_CREATED.version,
  timestamp: nowIso(),
  source: "user-service",
  data: {
    id: "user-123",
    email: "[email protected]",
    name: "John Doe"
  }
}, "user-123"); // partition key

Kafka Consumer

import { createConsumer } from "sellyguide-common/kafka";

await createConsumer(
  "user-service-group",
  ["user.created.v1"],
  async ({ topic, value, headers }) => {
    const event = JSON.parse(value);
    // Event işleme
  }
);

Event Standartları

Tüm eventler aynı zarfı kullanır:

{
  id: string;           // UUID, idempotency için
  type: string;         // "user.created"
  version: string;      // "v1"
  timestamp: string;    // ISO date
  source: string;       // "user-service"
  data: unknown;        // Event payload
  metadata?: object;    // Opsiyonel metadata
}

Topic adlandırması: {domain}.{action}.v{n} örn: user.created.v1

Breaking change durumunda yeni versiyon oluşturulur: user.created.v2

Dual-Build Desteği

Bu paket hem CommonJS hem ESM formatında build edilir:

• CommonJS: dist/*.cjs (Node.js require() ile kullanılabilir)
• ESM: dist/*.mjs (Modern import ile kullanılabilir)
• TypeScript: dist/*.d.ts (Tip tanımları)

package.json exports field'ı otomatik olarak doğru formatı seçer.

Geliştirme

Build

pnpm build

Test

pnpm test

Release

Değişiklik yaptıktan sonra:

pnpm changeset add

Changeset oluştur, commit ve push yap. GitHub Actions otomatik olarak release PR'ı oluşturur ve merge edilince npm'e publish eder.

Lisans

MIT