@cqrs-ddd/safe-stringify
Από την έκδοση 0.5.0 το
@cqrs-ddd/safe-stringifyαναπτύσσεται και δημοσιεύεται από το ddd-cqrs, με τεκμηρίωση στο aristoteliss.github.io/ddd-cqrs. Αυτός ο ιστότοπος τεκμηριώνει τη σειρά 0.4.x· οι εκδόσεις 0.1 έως 0.4 παραμένουν στο npm αμετάβλητες.
Δύο serializers JSON με αντίθετους στόχους, καθώς και τα βοηθητικά εργαλεία key-segment που κατασκευάζουν κλειδιά ταυτότητας. Χωρίς runtime εξαρτήσεις και χωρίς framework.
Αυστηρός (Strict): stableStringify, toStrictJsonValue |
Ασφαλής (Safe): safeStringify, safeSanitize, redactValue |
|
|---|---|---|
| Χρήση για | ταυτότητα: κλειδιά cache, αποτυπώματα idempotency, αποθηκευμένα snapshots | εμφάνιση: logs, payloads audit και dead-letter |
| Output | ντετερμινιστικό JSON, ταξινομημένα κλειδιά αντικειμένων σε κάθε επίπεδο, σταθερό μεταξύ εκδόσεων | αναγνώσιμο JSON κατά σειρά εισαγωγής· η μορφή μπορεί να εξελιχθεί |
| Μη υποστηριζόμενη είσοδος | πετά TypeError |
δεν πετά ποτέ σφάλμα |
| Μυστικά (Secrets) | δεν αποκρύπτει ποτέ, επειδή ένα κλειδί δεν πρέπει να αλλάζει | εξαιρεί και αποκρύπτει (redacts) κατόπιν αιτήματος |
Χρησιμοποιήστε τον αυστηρό serializer για οτιδήποτε ταυτοποιεί δεδομένα. Μην χρησιμοποιείτε ποτέ το safeStringify για κλειδί ή αποτύπωμα: το output του δεν είναι ταξινομημένο, αντικαθιστά τιμές που δεν μπορεί να αναπαραστήσει, και η μορφή του ενδέχεται να αλλάξει.
Εγκατάσταση
Ενότητα με τίτλο «Εγκατάσταση »npm install @cqrs-ddd/safe-stringify# orpnpm add @cqrs-ddd/safe-stringifyΑπαιτεί Node.js 22.12 ή νεότερο.
Δημοσιεύεται ως ES module· μια εφαρμογή CommonJS το φορτώνει με require(). Εάν προέρχεστε από την έκδοση 0.3.x, δείτε Αναβάθμιση από 0.3.x.
Αυστηρός serializer (Strict serializer)
Ενότητα με τίτλο «Αυστηρός serializer (Strict serializer) »import { stableStringify, toStrictJsonValue } from '@cqrs-ddd/safe-stringify';
stableStringify({ z: 1, a: { d: 2, c: new Date(0) } });// '{"a":{"c":"1970-01-01T00:00:00.000Z","d":2},"z":1}'
toStrictJsonValue({ b: 2, a: 1 }, true); // { a: 1, b: 2 }, a null-prototype object- Συμβολοσειρές (strings), booleans,
nullκαι πεπερασμένοι αριθμοί διατηρούνται. Τα Dates γίνονται ISO-8601 strings. Ένα αντικείμενο μεtoJSON()αντικαθίσταται από αυτό που επιστρέφει η μέθοδος. - Οτιδήποτε άλλο πετά
TypeError:undefined, συναρτήσεις,bigint, σύμβολα και ιδιότητες με κλειδί σύμβολο, μη πεπερασμένοι αριθμοί, μη έγκυρες ημερομηνίες, κυκλικές αναφορές, αραιοί πίνακες (sparse arrays),Map,Set,WeakMap,WeakSet,Error,RegExp,Promise,ArrayBufferκαι typed arrays. - Το
stableStringifyτυλίγει αυτή την αποτυχία σε έναTypeErrorτου οποίου τοcauseείναι το αρχικό σφάλμα. - Δομικά ισοδύναμες τιμές παράγουν πανομοιότυπες συμβολοσειρές byte προς byte, ανεξάρτητα από τη σειρά εισαγωγής των ιδιοτήτων τους. Τα κλειδιά ταξινομούνται κατά UTF-16 code unit, όπως κάνει το
Array.prototype.sort.
Ασφαλής serializer (Safe serializer)
Ενότητα με τίτλο «Ασφαλής serializer (Safe serializer) »import { DEFAULT_REDACT_KEYS, redactValue, safeStringify,} from '@cqrs-ddd/safe-stringify';
const payload: Record<string, unknown> = { user: 'jane', password: 'secret', amount: 10n };payload.self = payload;
safeStringify(payload);// '{"user":"jane","password":"secret","amount":"[bigint]","self":"[Circular]"}'
safeStringify(payload, { redactKeys: DEFAULT_REDACT_KEYS });// '{"user":"jane","password":"[REDACTED]","amount":"[bigint]","self":"[Circular]"}'
redactValue(payload); // a deep clone with DEFAULT_REDACT_KEYS masked-
Τα
safeStringify(value, options?, indent?)καιsafeSanitize(value, options?)δεν πετούν ποτέ σφάλμα. Οι κυκλικές αναφορές γίνονται"[Circular]", τα σφάλματα αναπτύσσονται σεname,message,stackκαι στις δικές τους απαριθμήσιμες ιδιότητες, και οι τιμές που δεν μπορούν να αναπαρασταθούν σε JSON αντικαθίστανται από ευανάγνωστο δείκτη ("[bigint]","[Function]","[Invalid Date]","[Binary Data]","[Stream]"). ΈναSet<string>στη θέση τωνoptionsδιαβάζεται ωςexcludeKeys. ΤοsafeStringify(undefined)επιστρέφει τη συμβολοσειρά'undefined'. -
Δεν αποκρύπτουν τίποτα εκτός αν περάσετε
redactKeys. ΤοredactValue(value, keys?)εφαρμόζει ταDEFAULT_REDACT_KEYSαπό προεπιλογή και διατηρεί πλούσιους τύπους (mode: 'clone'). -
SanitizeOptions:Επιλογή Αποτέλεσμα excludeKeysκλειδιά ή dot-paths που αφαιρούνται από το output· ακριβής ταύτιση με διάκριση πεζών/κεφαλαίων redactKeysκλειδιά ή dot-paths που αποκρύπτονται· ταυτίζονται αγνοώντας πεζά/κεφαλαία, _και-, επομένως τοrefreshTokenαποκρύπτει επίσης τοrefresh_tokenredactReplacementη μάσκα απόκρυψης· προεπιλογή REDACTED("[REDACTED]")mode'json'(προεπιλογή) μετατρέπει πλούσιους τύπους σε JSON-friendly τιμές·'clone'εκτελεί deep clone διατηρώντας τις κλάσεις τους -
Εξαίρεση και απόκρυψη (redaction), με ένα κλειδί να ταιριάζει σε οποιοδήποτε βάθος ή ένα dot-path να ταιριάζει σε μία συγκεκριμένη θέση:
safeStringify({ user: { profile: { email: 'x' }, token: 't' } },{ excludeKeys: ['user.profile'], redactKeys: ['token'], redactReplacement: '***' },);// '{"user":{"token":"***"}}'safeStringify({ when: new Date(0), tags: new Set(['a']), limits: new Map([['k', 1]]) });// '{"when":"1970-01-01T00:00:00.000Z","tags":["a"],"limits":{"k":1}}' -
Το
DEFAULT_REDACT_KEYSπαραθέτει κοινά ονόματα μυστικών (passwords, tokens, API keys, authorization headers, cookies, δεδομένα καρτών). Καμία λίστα δεν αναγνωρίζει κάθε μυστικό: προσθέστε τα ονόματα της δικής σας εφαρμογής.
Τμήματα κλειδιών (Key segments)
Ενότητα με τίτλο «Τμήματα κλειδιών (Key segments) »import { ABSENT_SEGMENT, escapeKeySegment, joinKeySegments,} from '@cqrs-ddd/safe-stringify';
joinKeySegments(['cache', 'tenant:a', undefined, 'user']);// 'cache:tenant\\:a:\\-:user'- Το
joinKeySegments(segments)διαφεύγει (escapes) κάθε τμήμα και τα ενώνει με:. ΤαundefinedκαιnullγίνονταιABSENT_SEGMENT(\-), επομένως τα['a', undefined]και['a', '']παράγουν διαφορετικά κλειδιά. - Το
escapeKeySegment(value)διαφεύγει πρώτα το\και μετά το:. Ένα τμήμα που είναι κυριολεκτικά\-γράφεται ως\\-, ώστε να μην συγκρούεται ποτέ με ένα απόν τμήμα.
Κατασκευή κλειδιού cache από ένα tenant, ένα όνομα αιτήματος και ένα αυστηρό αποτύπωμα του payload:
import { joinKeySegments, stableStringify } from '@cqrs-ddd/safe-stringify';import { createHash } from 'node:crypto';
function cacheKey(tenantId: string | undefined, name: string, payload: unknown): string { const fingerprint = createHash('sha256').update(stableStringify(payload)).digest('hex'); return joinKeySegments(['cache', tenantId, name, fingerprint]);}Το output του strict serializer και αυτές οι μορφές κλειδιών αποτελούν μέρος του συμβολαίου του πακέτου: η αλλαγή τους θα καθιστούσε ορφανή κάθε αποθηκευμένη εγγραφή cache, bucket ορίου ρυθμού και αποτύπωμα idempotency. Οι προδιαγραφές golden-output του πακέτου τις διατηρούν σταθερές.
Μετάβαση από το @nestjs-pipeline/core 0.1.x
Ενότητα με τίτλο «Μετάβαση από το @nestjs-pipeline/core 0.1.x »Το @nestjs-pipeline/core 0.1.x δεν εξήγαγε κανέναν serializer ή helper για τμήματα κλειδιών από το entry point του: τα safeStringify και safeSanitize βρίσκονταν στο εσωτερικό του module dist/helpers/safeStringify, και τα stableStringify, toStrictJsonValue, redactValue, DEFAULT_REDACT_KEYS, REDACTED καθώς και οι helpers τμημάτων κλειδιών δεν υπήρχαν. Κώδικας που εισήγαγε απευθείας από το εσωτερικό module μεταβαίνει σε αυτό το πακέτο:
// Πριν (0.1.x, εσωτερικό μονοπάτι)import { safeSanitize, safeStringify } from '@nestjs-pipeline/core/dist/helpers/safeStringify';
safeStringify(value, new Set(['token', 'ctx.sessionUser']), 2);
// Μετά (0.2.0)import { safeSanitize, safeStringify } from '@cqrs-ddd/safe-stringify';
safeStringify(value, { excludeKeys: ['token', 'ctx.sessionUser'] }, 2);- Το δεύτερο όρισμα
Set<string>εξακολουθεί να γίνεται δεκτό και σημαίνειexcludeKeys. - Το
safeStringify(undefined)πλέον επιστρέφει'undefined'αντί γιαundefined. - Χρησιμοποιήστε το
stableStringify, όχι τοsafeStringify, για οποιοδήποτε κλειδί ή αποτύπωμα κατασκευάζετε.
Άδεια χρήσης
Ενότητα με τίτλο «Άδεια χρήσης »Διπλή άδεια υπό AGPLv3 και Commercial License. Δείτε τα LICENSE και COMMERCIAL_LICENSE.txt στη ρίζα του repository για λεπτομέρειες.