superjson

قم بتسلسل تعبيرات JavaScript بأمان إلى مجموعة من JSON ، والتي تشمل التواريخ ، BigInts ، وأكثر من ذلك.

الميزات الرئيسية

• ؟ التسلسل الموثوق والخروج
• ؟ اكتب السلامة مع الإكمال التلقائي
• ؟ انصهار وقت التشغيل ضئيل
• ؟ إطار لاأدري
• ؟ إصلاح مثالي لـ Next.js القيود التسلسلية في getServerSideProps و getInitialProps

خلفية

في Blitz ، كافحنا مع قيود JSON. غالبًا ما نجد أنفسنا نعمل مع Date أو Map أو Set أو BigInt ، لكن JSON.stringify لا يدعم أيًا منها دون أن يمر بمشاحنات التحويل يدويًا!

يحل Superjson هذه المشكلات من خلال توفير غلاف رفيع على JSON.stringify و JSON.parse .

الرعاة

شعار Superjson بواسطة Numi:

ابدء

قم بتثبيت المكتبة باستخدام مدير الحزمة المفضل لديك ، على سبيل المثال:

 yarn add superjson

الاستخدام الأساسي

أسهل طريقة لاستخدام Superjson هي وظائف stringify و parse . إذا كنت تعرف كيفية استخدام JSON.stringify ، فأنت تعرف بالفعل Superjson!

بسهولة تهيئة أي تعبير تريده:

 import superjson from 'superjson' ;

const jsonString = superjson . stringify ( { date : new Date ( 0 ) } ) ;

// jsonString === '{"json":{"date":"1970-01-01T00:00:00.000Z"},"meta":{"values":{date:"Date"}}}'

وتحليل json الخاص بك مثل ذلك:

 const object = superjson . parse <
{ date : Date }
> ( jsonString ) ;

// object === { date: new Date(0) } 

استخدام متقدم

بالنسبة للحالات التي تريد فيها الوصول إلى مستوى المستوى إلى بيانات json و meta في الإخراج ، يمكنك استخدام وظائف serialize deserialize .

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

على سبيل المثال:

 const object = {
  normal : 'string' ,
  timestamp : new Date ( ) ,
  test : / superjson / ,
} ;

const { json , meta } = superjson . serialize ( object ) ;

/*
json = {
  normal: 'string',
  timestamp: "2020-06-20T04:56:50.293Z",
  test: "/superjson/",
};

// note that `normal` is not included here; `meta` only has special cases
meta = {
  values: {
    timestamp: ['Date'],
    test: ['regexp'],
  }
};
*/ 

باستخدام مع Next.js

لا تسمح لك getServerSideProps و getInitialProps و getStaticProps التي توفرها Next.js بنقل كائنات JavaScript مثل التواريخ. سوف يكون خطأ ما لم تقم بتحويل التواريخ إلى الأوتار ، إلخ.

لحسن الحظ ، Superjson هو أداة مثالية لتجاوز هذا القيد!

Next.js SWC Plugin (تجريبي ، v13 أو أعلى)

Next.JS SWC الإضافات هي تجريبية ، ولكن تعد بتسريع كبير. لاستخدام البرنامج المساعد Superjson SWC ، قم بتثبيته وإضافته إلى next.config.js :

yarn add next-superjson-plugin

 // next.config.js
module . exports = {
  experimental : {
    swcPlugins : [
      [
        'next-superjson-plugin' ,
        {
          excluded : [ ] ,
        } ,
      ] ,
    ] ,
  } ,
} ;

next.js (تحويل بابل مستقر)

قم بتثبيت المكتبة باستخدام مدير الحزمة المفضل لديك ، على سبيل المثال:

yarn add babel-plugin-superjson-next

أضف البرنامج المساعد إلى .babelrc. إذا لم يكن لديك واحدة ، فقم بإنشائها.

 {
  "presets" : [ "next/babel" ] ,
  "plugins" : [
    ...
    "superjson-next" // ?
  ]
}

منتهي! يمكنك الآن استخدام جميع أنواع بيانات JS بأمان في getServerSideProps / وما إلى ذلك.

API

التسلسل

يقوم بتسلسل أي قيمة javaScript في كائن متوافق مع JSON.

أمثلة

 const object = {
  normal : 'string' ,
  timestamp : new Date ( ) ,
  test : / superjson / ,
} ;

const { json , meta } = serialize ( object ) ;

إرجاع json و meta ، وكلاهما قيم متوافقة مع JSON.

هجر

يخرق إخراج Superjson مرة أخرى في قيمتك الأصلية.

أمثلة

 const { json , meta } = serialize ( object ) ;

deserialize ( { json , meta } ) ;

إرجاع your original value .

سلسلة

تسلسل ثم يثير قيمة javaScript الخاصة بك.

أمثلة

 const object = {
  normal : 'string' ,
  timestamp : new Date ( ) ,
  test : / superjson / ,
} ;

const jsonString = stringify ( object ) ;

إرجاع string .

تحليل

أخرس ثم يفرط في سلسلة JSON التي تم إرجاعها بواسطة stringify .

أمثلة

 const jsonString = stringify ( object ) ;

parse ( jsonString ) ;

إرجاع your original value .

---

يدعم Superjson العديد من الأنواع الإضافية التي لا يقوم بها JSON. يمكنك تسلسل كل هذه:

يكتب	بدعم من json ستاندرد؟	بدعم من Superjson؟
string	✅	✅
number	✅	✅
boolean	✅	✅
null	✅	✅
Array	✅	✅
Object	✅	✅
undefined		✅
bigint		✅
Date		✅
RegExp		✅
Set		✅
Map		✅
Error		✅
URL		✅

وصفات

يدعم SuperJson بشكل افتراضي فقط أنواع البيانات المدمجة للحفاظ على حجم الحزمة بأكبر قدر ممكن. فيما يلي بعض الوصفات التي يمكنك استخدامها لتوسيع نطاق أنواع البيانات غير الافتراضية.

ضعها في بعض ملفات الأداة المركزية وتأكد من تنفيذها قبل أي مكالمات أخرى SuperJSON . في مشروع Next.js ، سيكون _app.ts مكانًا جيدًا لذلك.

Decimal.js / Prisma.Decimal

 import { Decimal } from 'decimal.js' ;

SuperJSON . registerCustom < Decimal , string > (
  {
    isApplicable : ( v ) : v is Decimal => Decimal . isDecimal ( v ) ,
    serialize : v => v . toJSON ( ) ,
    deserialize : v => new Decimal ( v ) ,
  } ,
  'decimal.js'
) ; 

المساهمين

شكراً لهؤلاء الأشخاص الرائعين (مفتاح الرموز التعبيرية):

ديلان بروكس ؟ ️	سيمون نوت ؟ ️	براندون باير ؟	جيريمي ليبرمان ️	يوريس	Tomhooijenga ؟	Ademílson F. Tonato ️
بيوتر مونويد أوليشنوفيتش ؟	أليكس جوهانسون ️	سيمون إيدلمان ؟ ؟	سام غارسون ؟	مارك هيوز ؟	LXXYX	máximo mussini
بيتر ديككرز ؟	غابي أوليري	بنيامين	Ionut-cristian florescu ؟	كريس جونسون	نيكولاس تشيانغ ؟	داتنر
Ruessej ؟	jh.lee	Narumincho	Markus Greystone ؟	دارثمية	ماكس مالم	تايلر كولير
نيك كيبمان	توم ماكرايت ؟	بيتر بوداي ؟

يتبع هذا المشروع مواصفات جميع المساهمين. مساهمات من أي نوع ترحيب!

انظر أيضا

مكتبات أخرى تهدف إلى حل مشكلة مماثلة:

• تسلسل javaScript بقلم إريك فيريولو
• انخفض قيمة ريتش هاريس
• المجاور json بقلم دانييلي ريتشي