Գնահատել նախագիծը
← Բոլոր հրապարակումները

Նոր մոտեցում TypeScript գրադարանների ստեղծման համար, որոնք և հարմար են, և tree-shakable

Խելացի մոտեցում tree-shakable TypeScript գրադարաններ ստեղծելու համար, որը չի զոհաբերում օգտատիրոջ փորձը։

10 րոպե
type-level programmingtypescriptգրադարան

Այս հոդվածը ներկայացնում է tree-shakable TypeScript գրադարաններ ստեղծելու խելացի մոտեցում, որը չի զոհաբերում օգտատիրոջ փորձը։

Ընդհանուր պատկերն այսպիսին է՝

  • Օգտատերերը մեր գրադարանի API-ին դիմում են մեկ մուտքի կետով (մտածեք Zod-ի մասին)։
  • Դրա շնորհիվ նրանք կարող են օգտվել այնպիսի տեխնիկաներից, ինչպիսիք են method chaining-ը, builder pattern-ը և այլն։
  • Սակայն այս մուտքի կետն օգտագործելուց առաջ նրանք պետք է այն սկզբնավորեն՝ բացահայտորեն import անելով իրենց անհրաժեշտ ֆունկցիոնալությունները։ Յուրաքանչյուր լրացուցիչ import արված ֆունկցիոնալություն ընդլայնում է API-ն և մեծացնում վերջնական bundle-ի չափը։
  • Արդյունքում գրադարանի հեղինակը կարող է ավելի շատ հնարավորություններ առաքել՝ չվախենալով հանրային API-ի ուռճացումից, քանի որ օգտատերն է ընտրում, թե որ API-ները միացվեն և ներառվեն bundle-ում։

Այս գաղափարն ավելի լավ հասկանալու և այն ինչպես իրականացնելը տեսնելու համար եկեք քննենք կոնկրետ օրինակ։

Վերցնենք Zod-ը՝ լայնորեն օգտագործվող TypeScript-first սխեմաների վավերացման գրադարան։ Մշակողները սիրում են աշխատել դրա հետ, և այն ունի հարուստ էկոհամակարգ։

Սովորաբար այն օգտագործվում է այսպես՝

import { z } from "zod"; // 12.8 kB

const LoginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

// Throws error
LoginSchema.parse({ email: "", password: "" });

// Returns data as { email: string; password: string }
LoginSchema.parse({ email: "jane@example.com", password: "12345678" });

Ergonomics-ը Zod-ի ամենամեծ ուժեղ կողմերից մեկն է։ Այն տրամադրում է ինտուիտիվ, հակիրճ ինտերֆեյս սխեմաներ ստեղծելու համար՝ շղթայելով այնպիսի մեթոդներ, որոնք ոչինչ չեն փոփոխում (mutate)։

Մշակողի հարմարավետության տեսանկյունից method chaining-ը աջակցող API-ն ունի մեկ մեծ առավելություն՝ API-ի բացահայտում (discovery)։ Հենց որ գրում եք «.», ձեր IDE-ն ցույց է տալիս բոլոր հնարավոր գործողությունները, որոնք կարող եք ցանկանալ, իրենց ճշգրիտ տիպերի հետ միասին։

Սակայն կա մի թակարդ՝ ստատիկ import-ի չափը։ Zod-ի օգտագործումը սկսվում է մեկ z օբյեկտի import-ից և շարունակվում դրանից։ Հետևաբար, երբ Zod-ը օգտագործում ենք ինչ-որ բանի համար, պետք է import անենք բոլոր հասանելի մեթոդները։ Անկախ նրանից՝ կանչում ենք .brand, .superRefine թե .passthrough, դրանք բոլորը հայտնվում են մեր հավելվածի bundle-ում, քանի որ Zod-ը tree-shakable չէ։ Սակայն ի՞նչ է կոնկրետ դա նշանակում։

Ի՞նչ է tree-shakable գրադարանը

Կարճ ասած՝ tree shaking-ը չօգտագործվող կոդի հեռացումն է։ JavaScript bundler-ները դա իրականացնում են՝ վերլուծելով import և export հայտարարությունները և պարզելով, թե որ export-ները չեն օգտագործվում։ Tree shaking-ը վերաբերում է ոչ միայն ձեր սեփական կոդի մոդուլներին, այլև ձեր բոլոր կախվածություններին։

Ոչ բոլոր գրադարաններն են կարող tree-shake արվել։ Tree-shakable լինելու համար գրադարանը պետք է կազմակերպված լինի որոշակի ձևով։

Tree-shakable գրադարանի կառուցվածքի օրինակ

Նայեք այս օրինակին՝

// `tree-shakable-lib`

export const fun1 = () => "fun1";

export const fun2 = () => "fun2"

Եթե ձեր հավելվածն այնուհետև ունի այսպիսի տեսք՝

import { fun1 } from "tree-shakable-lib";

console.log(fun1());

ապա ստացված bundle-ը կլինի՝

const fun1 = () => "fun1";

console.log(fun1());

Ինչպես տեսնում եք, fun2-ի սահմանումը բաց է թողնվել bundle-ից, ինչը այն դարձնում է ավելի փոքր։

Ոչ tree-shakable գրադարանի կառուցվածքի օրինակ

Այժմ նայեք այս օրինակին՝

// `non-tree-shakable-lib`

export const lib = {
    fun1: () => "val1",
    fun2: () => "val2"
}

Եթե ձեր հավելվածն այնուհետև ունի այսպիսի տեսք՝

import { lib } from "./non-tree-shakable-lib.js";

console.log(lib.fun1());

ապա ստացված bundle-ը կլինի՝

const lib = {
    fun1: () => "val1",
    fun2: () => "val2"
};

console.log(lib.fun1());

Այստեղ, թեև օգտագործվում է միայն fun1 մեթոդը, ամբողջ lib օբյեկտը պետք է մտնի bundle-ի մեջ, քանի որ bundler-ը չի կարող անվտանգ կերպով դուրս հանել օբյեկտի կամ դասի միայն մի մասը։

Խորհուրդ. Rollup REPL-ը թույլ է տալիս հեշտությամբ խաղալ tree shaking-ի հետ առցանց

Վերը նշվածը tree shaking-ի ավելի լայն թեմայի միայն կարճ ներածություն է, բայց այս հոդվածի նպատակների համար դա բավարար է։

Valibot = Zod tree shaking-ով։

Այժմ, երբ գիտենք, թե ինչպես կառուցել tree-shakable գրադարան, ինչպե՞ս կարող էինք Zod-ը դարձնել tree-shakable։ Վերջերս թողարկված Valibot անունով մի գրադարան փորձ է արել։

Ահա թե ինչ տեսք ունի մեր նախորդ Zod օրինակը Valibot-ով վերագրելուց հետո՝

import { email, minLength, object, parse, string } from 'valibot'; // 0.85 kB

const LoginSchema = object({
  email: string([email()]),
  password: string([minLength(8)]),
});

// Throws error
parse(LoginSchema, { email: '', password: '' });

// Returns data as { email: string; password: string }
parse(LoginSchema, { email: 'jane@example.com', password: '12345678' });

API-ն ծանոթ է թվում, բայց այն ավելի շատ թեքվում է ֆունկցիոնալ ոճի կողմը՝

  • LoginSchema-ի վրա parse մեթոդ կանչելու փոխարեն մենք կանչում ենք առանձին parse ֆունկցիա և սխեման փոխանցում արգումենտով։
  • string validator-ին լրացուցիչ սահմանափակումներ կետով շղթայելու փոխարեն մենք դրանք փոխանցում ենք որպես արգումենտներ։ Յուրաքանչյուր սահմանափակում առանձին import արվող ֆունկցիա է։

Սա համապատասխանում է tree-shakable գրադարանների պարզեցված կանոնին. մաքուր ֆունկցիաների հավաքածու export անող գրադարանը, ամենայն հավանականությամբ, tree-shakable է։ Եվ դա ճիշտ է Valibot-ի համար։ Նայեք առաջին տողի մեկնաբանության մեջ նշված import-ի չափին. այն 15 անգամ փոքր է Zod-ինից, մինչդեռ կատարում է ճիշտ նույն աշխատանքը։ Բնականաբար, import-ի չափը կմեծանա, երբ ձեր հավելվածն օգտագործի ավելի շատ ֆունկցիաներ, բայց գործնականում հազվադեպ է պատահում, որ օգտագործվի գրադարանի ֆունկցիոնալության 100%-ը, հատկապես այնպիսի ունիվերսալ գրադարանների դեպքում, ինչպիսիք են Zod-ը և Valibot-ը։

Valibot-ը սակայն մեկ խնդիր ունի։ Նրա ֆունկցիոնալ API-ն գրադարանը դարձնում է tree-shakable, բայց ես կասեի, որ այստեղ այն նաև ռիսկ է պարունակում API-ն ավելի քիչ հարմար դարձնելու։ Ergonomics-ի մասին դատելն ավելի դժվար է, քան import-ի չափերինը, քանի որ դրանք ավելի նուրբ են և կարող են կախված լինել անձնական նախասիրությունից։ Այդուհանդերձ, կարծում եմ՝ Zod-ի մշակողի համար բարեկամական լինելը այն դարձնում է գերազանց։ Ահա Valibot-ի API-ի մի քանի թերություններ՝

  • Չի կարելի հեշտությամբ ուսումնասիրել API-ն՝ առանց IDE-ից դուրս գալու։
  • Յուրաքանչյուր սխեմա կառուցելը նշանակում է կամ սխեմայի սահմանումից վեր թռչել դեպի import հայտարարությունը՝ նոր ֆունկցիաներ ավելացնելու համար, կամ դրանք բոլորը նախապես թվարկել։

Correttore. երկու աշխարհի լավագույնը

Արագ ամփոփենք, թե ինչ ենք անցել՝

  • Zod-ն առաջարկում է գերազանց մշակողի փորձ (DX), բայց չի կարող tree-shake արվել։
  • Valibot-ը կարող է tree-shake արվել, բայց դրա API-ն կարող է համարվել ավելի քիչ հարմար։

Սա բարձրացնում է մի պարզ հարց. կարո՞ղ ենք ստեղծել գրադարան՝ Zod-ի նույն API-ով, որն ինչ-որ կերպ նաև tree-shakable է։ Այո, կարող ենք, և հենց այդ մասին է այն տեխնիկան, որը պատրաստվում եմ ցույց տալ։ Որպես proof of concept ես ստեղծեցի Correttore՝

import { email, minLength, object, initCorrettore, string } from "correttore"; // 0.54 kB

export const c = initCorrettore({
  string,
  email,
  object,
  minLength,
});

const LoginSchema = c.object({
  email: c.string().email(),
  password: c.string().minLength(8),
});

// Throws error
LoginSchema.parse({ email: "", password: "" });

// Returns data as { email: string; password: string }
LoginSchema.parse({ email: "jane@example.com", password: "12345678" });

Ավելի մանրամասն՝

  1. Առաջին տողում մենք import ենք անում initCorrettore-ը՝ API-ի բոլոր «մասերի» հետ միասին, որոնք մեր հավելվածը պատրաստվում է օգտագործել։
  2. Մենք կանչում ենք initCorrettore՝ c փոփոխական ստեղծելու և export անելու համար։ Այս c-ն խաղում է Zod-ի ծանոթ z-ի դերը։ Հավելվածի ցանկացած այլ տեղում մենք պարզապես import անեինք c-ն այս ֆայլից։
  3. Մենք կառուցում ենք LoginSchema այն ձևով, որը ճիշտ նման է Zod-ինին, միայն օգտագործելով մեր c օբյեկտը։ Տարբերությունն այն է, որ մեթոդները շղթայելիս մենք տեսնում ենք միայն նրանք, որոնք նախկինում import ենք արել և փոխանցել initCorrettore ֆունկցիային։ Օրինակ՝ initCorrettore կանչից email-ը հեռացնելը string()-ից կվերացներ email մեթոդը, և սխեմայի օբյեկտը կառաջացներ կոմպիլյացիայի ժամանակի TypeScript սխալ։ Ընդհակառակը, import անելը և ավելացնելը, ասենք, number validator, այն կերևար c օբյեկտի վրա որպես վավեր մեթոդ։

Մնացած ամեն ինչ աշխատում է ինչպես Zod-ում, բայց import-ի չափը ընդամենը մի փոքր ավելի քան 500 բայթ է՝ 25 անգամ փոքր։

Որն է գաղտնի բաղադրիչը

Նման գրադարան գրելու համար պետք է ընդամենը երկու բաղադրիչ՝

  1. Proxy օբյեկտներ
  2. Մի փոքր type-level programming։

Proxy

Proxy-ները թույլ են տալիս կանխել և վերասահմանել ցանկացած օբյեկտի հիմնարար գործողությունները։ Ստորև բերված օրինակում մենք someObject-ը փաթաթում ենք proxy-ի մեջ, որպեսզի յուրաքանչյուր հատկության հասանելիությունը լոգավորվի հատկության անվան հետ միասին։

const someObject = {
    a: 100,
    b: "hello"
}

const proxyObject = new Proxy(someObject, {
    get: (target, prop) => {
        console.log(`property ${String(prop)} was called!`);
        return target[prop as keyof typeof target];
    }
});

proxyObject.a; // logs: "property a was called!"
proxyObject.b; // logs: "property b was called!"

Proxy handler-ում (Proxy կոնստրուկտորին փոխանցվող երկրորդ արգումենտ) մենք կարող ենք անել գրեթե ամեն ինչ։ Ավելի շատ օրինակների և API-ի ամբողջական ակնարկի համար նայեք MDN Web Docs-ը Proxy-ի մասին։

Այսպիսով, հիմնական գաղափարը հետևյալն է. երբ օգտատերը սկզբնավորում է Correttore-ը parser-ների record-ով (ինչպիսիք են number, string, boolean և այլն), մենք proxy ենք կառուցում դատարկ օբյեկտից և պարզապես դինամիկ կերպով գործարկում ենք parser-ները, երբ դրանք կանչվում են՝

// NOTE: the code below works, but for now, the `c` object is typed as `any`

// mocked parsers for brevity
const string = (x: any) => `${x} is a string`;
const number = (x: any) => `${x} is a number`;
const boolean = (x: any) => `${x} is a boolean`;

const simplifiedInitCorrettore = (parsers: Record<string, (arg: any) => string>) => {
    return new Proxy({} as any, {
        get(target, key) {
            if (key in parsers) {
                return (args: any) => parsers[key as any](args);
            } else {
                throw new Error("Unknown parser");
            }
        }
    })
}

const c = simplifiedInitCorrettore({
    string,
    number,
    // we purposely omit boolean parser here
});

console.log(c.string("hello")); // -> "hello is a string"
console.log(c.number(42)); // -> "hello is a string"
console.log(c.boolean(true)); // -> Error: Unknown parser

Վերը բերված իրականացումը պատկերացնում է ընդհանուր հայեցակարգը, բայց դեռ չի աջակցում method chaining-ի կամ ճիշտ տիպավորման։

Method chaining-ը (օրինակ՝ c.string().email()) հնարավոր դարձնելու համար մենք կներմուծենք parsersChain փոփոխական, որը պահում է method chain-ի յուրաքանչյուր parser-ը (*)։ Այսպիսով, օրինակ՝ c.string().email()-ը համապատասխանում է [stringParser, emailParser]-ին։ Միայն երբ .parse-ը կանչվում է, մենք անցնում ենք բոլոր parser-ների վրա և ստուգում արգումենտը դրանցից յուրաքանչյուրի դեմ (**)։

const createParserProxy = (
  p: Parser<any>,
  parsers: Record<string, (...args: any) => Parser<any>>,
  parsersChain: Parser<any>[]
) =>
  new Proxy(p, {
    get(target, key) {
      if (key === "parse") { // (**)
        return (arg: any) => {
          parsersChain.forEach((p) => p.parse(arg));
          return target.parse(arg);
        };
      }
      if (key in parsers) {
        return (args: any) =>
          createParserProxy(parsers[key as any](args), parsers, [
            ...parsersChain, // (*)
            parsers[key as any](args),
          ]);
      } else {
        throw new Error(`Unknown parser ${key as string}`);
      }
    },
  });

export const initCorrettore = <
  Parsers extends Record<string, (...args: any) => Parser<any>>
>(
  parsers: Parsers
): calculateCorrettoreType<keyof Parsers> => {
  return new Proxy({} as calculateCorrettoreType<keyof Parsers>, {
    get(target, key) {
      if (key in parsers) {
        return (args: any) =>
          createParserProxy(parsers[key as any](args), parsers, [
            parsers[key as any](args),
          ]);
      } else {
        throw new Error(`Unknown parser ${key as string}`);
      }
    },
  });
};

Իրականացումը լի է any տիպերով, բայց ստացված c օբյեկտը ճիշտ է տիպավորված as calculateCorrettoreType<keyof Parsers> հատվածի շնորհիվ։

Type-Level Programming

Սա այն կետն է, որտեղ type-level programming-ը մտնում է պատկերի մեջ։ Պետք է գրել տիպ, որը արտացոլում է import արված parser-ների տրամադրված record-ը։ Մեծ մասամբ դա պարզ է. բարդ մասն այն է, որ այն աշխատի այնպես, որ, ասենք, email parser-ը հասանելի լինի միայն string() parser-ից հետո, և ոչ, օրինակ, number()-ից հետո։

// Full correttore type with all parsers and extensions
type FullCorrettore = {
  // StringParser is an object that includes the `parse` method as well
  // as all the other parsers that can occur after `string()`, for example
  // `email` or `minLength`. 
  string: () => StringParser;

  // Similarly for this one.
  number: () => NumberParser;

  // see ObjectParser implementation here:
  // based on the object parser from the author's proof-of-concept library
  object: <S extends Record<string, Parser<any>>>(schema: S) => ObjectParser<S>;
};

// given the list of imported parsers and validator, calculate a type for the correttore object
type calculateCorrettoreType<
  features,
  parser extends Record<string, (...args: any[]) => any> = FullCorrettore
> = {
  [k in Extract<keyof parser, features | "parse">]: k extends "parse"
    ? parser[k]
    : (
        ...args: Parameters<parser[k]>
      ) => calculateCorrettoreType<features, ReturnType<parser[k]>>;
};

Ամփոփում

Այս հոդվածում ցուցադրված տեխնիկան ակնհայտորեն արդարացնում է իրեն օգտատիրոջ փորձի և bundle-ի չափի օպտիմիզացման առումով, բայց արդյո՞ք այն ունի թերություններ։

Գրադարանն օգտագործող մարդկանց համար՝ գրեթե ոչ։ Ինչ-որ մեկը կարող է ասել, որ գրադարանի սկզբնավորումը լրացուցիչ քայլ է, և երբ օգտատիրոջը import-ի չափը չի մտահոգում (ինչպես server-side հավելվածներում), դա միայն բարդություն է ավելացնում։ Սակայն դա կարելի է լուծել՝ գրադարանից export անելով լրացուցիչ նախապես սկզբնավորված օբյեկտ, որը բացահայտում է ամբողջական API-ն։

Քանի որ այս տեխնիկան օպտիմիզացնում է օգտատիրոջ փորձը, այն գրադարանների հեղինակների կյանքն ավելի դժվարացնում է։ Նախ՝ proxy-ով բոլոր մասերը իրար կապելը սովորաբար պարզ է, բայց դա նշանակում է գրել կոդ, որը type-safe չէ և լի է any-ներով։ Երկրորդ՝ գրադարանի սպառողին ճիշտ տիպավորում տրամադրելը կարող է պահանջել լուրջ type gymnastics, ինչը կարող է վախեցնող թվալ type-level աշխատանքին նոր ծանոթացող ծրագրավորողների համար։


Սիրով կլսեի ձեր կարծիքը այս մասին. թողեք մեկնաբանություն ստորև։

Եթե ցանկանում եք օգնել այս նախագիծը հասցնել production-ready վիճակի, բացեք PR՝ փոփոխություններով, որոնք այն ավելի են մոտեցնում Zod-ի հետ 1:1 համատեղելի API-ի։