Μετάβαση στο περιεχόμενο

Πρώτα βήματα

Σε έναν άδειο κατάλογο, εγκαταστήστε το pipeline, το behavior επικύρωσης και το Zod:

pnpm add @cqrs-ddd/pipeline @cqrs-ddd/pipeline-zod zod

Αποθηκεύστε το παρακάτω ως create-order.mjs:

import { createPipeline, logging } from '@cqrs-ddd/pipeline';
import { validated, ZodValidationError } from '@cqrs-ddd/pipeline-zod';
import { z } from 'zod';

const pipeline = createPipeline({
  globalBehaviors: { before: [logging({ requestResponseLogLevel: 'none' })] },
});

const order = z.object({
  orderId: z.string().min(1),
  amount: z.number().positive(),
});

const createOrder = pipeline.wrap(
  { name: 'createOrder', kind: 'command' },
  validated(order),
)(async (input) => ({ id: input.orderId, status: 'created' }));

console.log(await createOrder({ orderId: 'ord_123', amount: 49.99 }));

try {
  await createOrder({ orderId: 'ord_bad', amount: -1 });
} catch (error) {
  if (!(error instanceof ZodValidationError)) throw error;
  console.log('Invalid order rejected before the function ran');
}

Εκτελέστε το:

node create-order.mjs

Η standard output δείχνει την καταγεγραμμένη κλήση, το αποτέλεσμα της έγκυρης παραγγελίας και την απόρριψη της μη έγκυρης. Το correlation id και η διάρκεια διαφέρουν σε κάθε εκτέλεση:

[0199c2d4-…] COMMAND createOrder → createOrder completed in 1.08ms createOrder
{ id: 'ord_123', status: 'created' }
Invalid order rejected before the function ran

Το logging() αναφέρει επίσης την απορριφθείσα κλήση στη standard error, ως createOrder failed με το ZodValidationError και το stack του. Πρόκειται για την καταγραφή της αποτυχίας που προκαλεί το ίδιο το παράδειγμα· η διεργασία τερματίζει με κωδικό 0. Η συνάρτηση επιστρέφει ένα αντικείμενο και δεν αποθηκεύει τίποτα: δεν υπάρχει βάση δεδομένων, framework ή βήμα build.

Η υπόλοιπη σελίδα παρουσιάζει τα ίδια κομμάτια ένα προς ένα.

pnpm add @cqrs-ddd/pipeline

Τα πακέτα απαιτούν Node.js 22.12 ή νεότερο· το @cqrs-ddd/mikro-orm απαιτεί 22.17 ή νεότερο, όπως και το MikroORM 7. Ο έλεγχος κυκλοφορίας (release check) φορτώνει επίσης κάθε entry point σε Bun· οι σουίτες δοκιμών εκτελούνται μόνο σε Node.js και κανένα άλλο runtime δεν δοκιμάζεται. Τα πακέτα δημοσιεύονται ως ES modules· μια εφαρμογή CommonJS τα φορτώνει με require().

Ένα pipeline κρατά τα instances των behaviors και τα behaviors που ισχύουν για κάθε λειτουργία. Δημιουργήστε το μία φορά, σε δικό του module:

// pipeline.ts
import { createPipeline, LoggingBehavior, logging } from '@cqrs-ddd/pipeline';

export const pipeline = createPipeline({
  behaviors: [new LoggingBehavior(console)],
  globalBehaviors: { before: [logging({ requestResponseLogLevel: 'log' })] },
});

Τα behaviors είναι τα instances, ένα ανά κλάση behavior· ένα behavior που τοποθετείται χωρίς instance κατασκευάζεται χωρίς ορίσματα. Το globalBehaviors τοποθετεί behaviors γύρω από κάθε λειτουργία που τυλίγεται.

Το pipeline.wrap(options, ...entries) επιστρέφει έναν wrapper. Όταν εφαρμοστεί σε μια συνάρτηση, επιστρέφει μια νέα async συνάρτηση που εκτελεί τα behaviors γύρω της:

import { pipeline } from './pipeline.js';

const prices = new Map([
  ['apple', 120],
  ['pear', 90],
]);

export const getPrice = pipeline.wrap({ name: 'getPrice', kind: 'query' })(
  async (sku: string) => prices.get(sku),
);

await getPrice('apple');

Μια απλή συνάρτηση χρειάζεται ένα name, με το οποίο τα κλειδιά και τα logs ξεχωρίζουν τις λειτουργίες, και ένα kind: ένα query διαβάζει, ένα command αλλάζει κατάσταση, ένα event αντιδρά. Τα behaviors χρησιμοποιούν το kind για να αποφασίσουν τι ισχύει· το idempotency, για παράδειγμα, ισχύει για commands.

Ο ίδιος wrapper γίνεται decorator μεθόδου, με τους standard decorators της TypeScript ή με experimentalDecorators:

class Prices {
  private readonly store = new Map([['apple', 120]]);

  @pipeline.wrap({ kind: 'query' })
  async find(sku: string) {
    return this.store.get(sku);
  }
}

Μια μέθοδος ονομάζεται Class.method (εδώ Prices.find), εκτός αν τα options της δίνουν όνομα.

Κάθε λειτουργία είναι ένα πακέτο. Εγκαταστήστε το, δώστε στο pipeline ένα instance και προσθέστε την καταχώρισή του εκεί που ισχύει:

pnpm add @cqrs-ddd/pipeline-zod zod
import { validated } from '@cqrs-ddd/pipeline-zod';
import { z } from 'zod';

export const placeOrder = pipeline.wrap(
  { name: 'placeOrder', kind: 'command' },
  validated(z.object({ sku: z.string(), qty: z.coerce.number().int().positive() })),
)(async (order) => ({ ...order, status: 'placed' }));