Նոր մոտեցում TypeScript գրադարանների ստեղծման համար, որոնք և հարմար են, և tree-shakable
Խելացի մոտեցում tree-shakable TypeScript գրադարաններ ստեղծելու համար, որը չի զոհաբերում օգտատիրոջ փորձը։
Այս հոդվածը ներկայացնում է 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ֆունկցիա և սխեման փոխանցում արգումենտով։stringvalidator-ին լրացուցիչ սահմանափակումներ կետով շղթայելու փոխարեն մենք դրանք փոխանցում ենք որպես արգումենտներ։ Յուրաքանչյուր սահմանափակում առանձին 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" });
Ավելի մանրամասն՝
- Առաջին տողում մենք import ենք անում
initCorrettore-ը՝ API-ի բոլոր «մասերի» հետ միասին, որոնք մեր հավելվածը պատրաստվում է օգտագործել։ - Մենք կանչում ենք
initCorrettore՝cփոփոխական ստեղծելու և export անելու համար։ Այսc-ն խաղում է Zod-ի ծանոթz-ի դերը։ Հավելվածի ցանկացած այլ տեղում մենք պարզապես import անեինքc-ն այս ֆայլից։ - Մենք կառուցում ենք
LoginSchemaայն ձևով, որը ճիշտ նման է Zod-ինին, միայն օգտագործելով մերcօբյեկտը։ Տարբերությունն այն է, որ մեթոդները շղթայելիս մենք տեսնում ենք միայն նրանք, որոնք նախկինում import ենք արել և փոխանցելinitCorrettoreֆունկցիային։ Օրինակ՝initCorrettoreկանչիցemail-ը հեռացնելըstring()-ից կվերացներemailմեթոդը, և սխեմայի օբյեկտը կառաջացներ կոմպիլյացիայի ժամանակի TypeScript սխալ։ Ընդհակառակը, import անելը և ավելացնելը, ասենք,numbervalidator, այն կերևարcօբյեկտի վրա որպես վավեր մեթոդ։
Մնացած ամեն ինչ աշխատում է ինչպես Zod-ում, բայց import-ի չափը ընդամենը մի փոքր ավելի քան 500 բայթ է՝ 25 անգամ փոքր։
Որն է գաղտնի բաղադրիչը
Նման գրադարան գրելու համար պետք է ընդամենը երկու բաղադրիչ՝
- Proxy օբյեկտներ
- Մի փոքր 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-ի։