أصدرت LogTape، وهي مكتبة تسجيل منظمة بدون تبعية لـ JavaScript وTypeScript، الإصدار 0.6.0. ما الذي تغير؟

تجاوز أحواض المسجل الأم

إحدى ميزات LogTape هي وراثة المصارف من خلال الفئات الهرمية. على سبيل المثال، إذا قمت بإعداد جهازي تسجيل مثل هذا:

import { configure, getConsoleSink, getFileSink } from "@logtape/logtape";

await configure({
  sinks: {
    console: getConsoleSink(),
    file:    getFileSink("app.log"),
  },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"] },
  ],
});

سيتم حفظ السجلات المكتوبة في مسجل ["app"] فقط في ملف app.log، ولكن سيتم حفظ السجلات المكتوبة في مسجل ["app"، "module"] في كليهما ملف app.log والإخراج إلى وحدة التحكم. وذلك لأن المسجل ["app"، "module"] يرث المصارف من فئته الأصلية ["app"].

ومع ذلك، في بعض الأحيان قد لا ترغب في هذا السلوك. بدءًا من LogTape 0.6.0، يمكنك الآن تجاوز أحواض المسجل الأصلي. على سبيل المثال، إذا قمت بتمكين خيارparentSinks: "override" لمسجل الطفل مثل هذا:

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

سيتم حفظ السجلات المكتوبة إلى مسجل ["app"] فقط في ملف app.log، وسيتم إخراج السجلات المكتوبة إلى مسجل ["app"، "module"] فقط إلى وحدة التحكم. وذلك لأن المسجل الفرعي ["app"، "module"] قد تجاوز أحواض المسجل ["app"].

بالطبع، القيمة الافتراضية هيparentSinks: "يرث"، لذلك إذا لم تحدد الخيار، فسوف يتصرف كما كان من قبل.

إذا كنت مهتمًا بخلفية إضافة هذه الميزة، فيرجى الرجوع إلى إصدار GitHub رقم 15.

السماح بالمسافات البادئة/اللاحقة للعناصر النائبة في قوالب الرسائل

في الإصدارات السابقة، إذا قمت بتسجيل الدخول بهذه الطريقة:

logger.info("Hello, { name }!", { name: "Alice" });

خلافا للتوقعات، سجل مرحبا، غير محدد! سيتم إنشاؤها. وذلك لأن العنصر النائب { name } يتضمن أحرف مسافات، لذلك تم البحث عن خاصية " name " بدلاً من " name ". بمعنى آخر، كان عليك إما إزالة المسافات من العنصر النائب مثل هذا:

logger.info("Hello, {name}!", { name: "Alice" });

أو أضف نفس المسافات إلى اسم الخاصية الفعلي مثل هذا:

logger.info("Hello, { name }!", { " name ": "Alice" });

على الرغم من أن هذا لم يكن خطأً تمامًا، إلا أنه كان سلوكًا عرضة للأخطاء اعتمادًا على عادات البرمجة.

ومع ذلك، بدءًا من LogTape 0.6.0، حتى لو كانت هناك مسافات في بداية العنصر النائب ونهايته، فإنه سيبحث عن اسم خاصية بدون مسافات. على سبيل المثال، إذا قمت بالتسجيل بهذه الطريقة:

logger.info("Hello, { name }!", { name: "Alice" });

كما هو متوقع، سجل مرحبًا، أليس! سيتم إنشاؤه.

ومع ذلك، إذا كانت هناك خاصية تتطابق تمامًا مع أحرف المسافات، فسيتم منح الأولوية لذلك. على سبيل المثال، إذا قمت بالتسجيل بهذه الطريقة:

logger.info("Hello, { name }!", { name: "Alice", " name ": "Bob" });

مرحبًا بوب! سيتم تسجيله بدلاً من Hello, Alice!.

إذا كنت مهتمًا بخلفية إضافة هذه الميزة، فيرجى الرجوع إلى إصدار GitHub رقم 16.

خاصية LogRecord.rawMessage

LogRecord هو نوع بيانات يمثل سجلاً قبل إخراجه وتنسيقه بواسطة LogTape.

على الرغم من أن خاصية LogRecord.message موجودة بالفعل، إلا أن هذه الخاصية تحتوي على النتيجة بعد استبدال العناصر النائبة في قالب الرسالة بقيم الخصائص الفعلية. كان هذا كافيًا في معظم الحالات، ولكن عندما تكون وجهة إخراج السجل (المصدر) عبارة عن نظام تسجيل آخر، فقد ترغب في إخراج قالب الرسالة الأصلي وقيم الخصائص بشكل منفصل، مما يسمح لنظام تسجيل الاستلام باستبدال العناصر النائبة في قالب الرسالة بالخاصية القيم مباشرة.

إن LogRecord.rawMessage الذي تمت إضافته في LogTape 0.6.0 هو خاصية لهذا الغرض بالضبط، ويحتوي على الحالة الأصلية لقالب الرسالة مع عدم استبدال العناصر النائبة. على سبيل المثال، إذا قمت بالتسجيل بهذه الطريقة:

logger.info("Hello, {name}!", { name: "Alice" });

بينما تحتوي رسالة LogRecord.message على القيمة ["Hello, "، "Alice"، "!"]، فإن LogRecord.rawMessage ستحتوي على القيمة "Hello, {name}!".

إذا كنت مهتمًا بخلفية إضافة هذه الميزة، فيرجى الرجوع إلى إصدار GitHub رقم 17.

تنسيقات نصية مدمجة قابلة للتخصيص

منسق النص عبارة عن واجهة تحدد كيفية تنسيق كل سجل في نص في أحواض الدفق، وأحواض الملفات، وما إلى ذلك. تعريف النوع الفعلي بسيط للغاية:

export type TextFormatter = (record: LogRecord) => string;

ومع ذلك، قد يكون تحديد منسق النص مباشرة في كل مرة أمرًا مرهقًا، لذلك يحتوي LogTape على defaultTextFormatter وansiColorFormatter الذي يمكنك استخدامه. حتى الآن، نظرًا لعدم إمكانية تكوين إضافي، كان عليك قبول التنسيق المحدد مسبقًا كما هو. على سبيل المثال، إذا لم يعجبك أن يتم إخراج مستويات السجل مثل "تحذير" كاختصارات من ثلاثة أحرف مثل WRN، كان عليك تنفيذ TextFormatter من البداية.

ومع ذلك، بدءًا من LogTape 0.6.0، يمكنك تخصيص إعدادات التنسيق المختلفة حسب رغبتك من خلال وظائف getDefaultTextFormatter() وgetAnsiColorFormatter() دون الحاجة إلى تنفيذ TextFormatter من البداية.

على سبيل المثال، إذا كنت تريد تمثيل مستويات السجل مثل "تحذير" كحرف كبير واحد W، فيمكنك تكوينه على النحو التالي:

const myFormatter = getDefaultTextFormatter({ level: "L" });

أو إذا كنت تريد حذف التاريخ والمنطقة الزمنية من الطابع الزمني وإظهار الوقت فقط، فيمكنك تكوينه على النحو التالي:

const myFormatter = getDefaultTextFormatter({ timestamp: "time" });

للحصول على وصف لمزيد من خيارات التنسيق، يرجى الرجوع إلى الوثائق ذات الصلة.

إذا كنت مهتمًا بخلفية إضافة هذه الميزة، فيرجى الرجوع إلى إصدار GitHub رقم 13.

احصل عليه من JSR وnpm

يتوفر LogTape 0.6.0 بالفعل على JSR وnpm، لذا احصل عليه الآن!

deno add @logtape/[email protected]  # Deno
npm  add @logtape/[email protected]  # npm
pnpm add @logtape/[email protected]  # pnpm
yarn add @logtape/[email protected]  # Yarn
bun  add @logtape/[email protected]  # Bun

تسجيل سعيد!