|
| 1 | +/* eslint-disable @typescript-eslint/triple-slash-reference */ |
| 2 | +/// <reference types="node" /> |
| 3 | + |
| 4 | +declare module '@mrhenry/polyfill-library' { |
| 5 | + import type { Readable } from 'node:stream' |
| 6 | + |
| 7 | + export interface PolyfillConfig { |
| 8 | + aliases: string[], |
| 9 | + dependencies: string[], |
| 10 | + spec: string, |
| 11 | + repo: string, |
| 12 | + docs: string, |
| 13 | + license: string, |
| 14 | + notes: string[], |
| 15 | + browsers: { [browser: string]: string }, |
| 16 | + install: { [key: string]: string | string[] }, |
| 17 | + } |
| 18 | + |
| 19 | + export interface PolyfillMeta extends PolyfillConfig { |
| 20 | + detectSource: string, |
| 21 | + baseDir: string, |
| 22 | + hasTests: boolean, |
| 23 | + isTestable: boolean, |
| 24 | + isPublic: boolean, |
| 25 | + size: number, |
| 26 | + } |
| 27 | + |
| 28 | + export interface Options { |
| 29 | + /** |
| 30 | + * Name of the JavaScript function to call after the polyfill bundle is loaded. |
| 31 | + * @default false |
| 32 | + */ |
| 33 | + callback?: false | string, |
| 34 | + /** |
| 35 | + * Whether to return the minified or raw implementation of the polyfills. |
| 36 | + * @default true |
| 37 | + */ |
| 38 | + minify?: boolean, |
| 39 | + /** |
| 40 | + * Whether to return all polyfills or no polyfills if the user-agent is unknown or unsupported. |
| 41 | + * @default 'polyfill' |
| 42 | + */ |
| 43 | + unknown?: 'ignore' | 'polyfill', |
| 44 | + /** |
| 45 | + * Which features should be returned if the user-agent does not support them natively. |
| 46 | + * @default {} |
| 47 | + */ |
| 48 | + features?: { [featureName: string]: { flags: Flag[] | Set<Flag> } }, |
| 49 | + /** |
| 50 | + * Which features should be excluded from the returned object. |
| 51 | + * @default [] |
| 52 | + */ |
| 53 | + excludes?: string[], |
| 54 | + /** |
| 55 | + * The user-agent string to check each feature against. |
| 56 | + * @default '' |
| 57 | + */ |
| 58 | + ua?: { |
| 59 | + getFamily: () => string, |
| 60 | + satisfies: () => boolean, |
| 61 | + isUnknown: () => boolean, |
| 62 | + }, |
| 63 | + /** |
| 64 | + * Whether to include a script that reports anonymous usage data in the polyfill bundle. |
| 65 | + * @default false |
| 66 | + */ |
| 67 | + rum?: boolean, |
| 68 | + } |
| 69 | + |
| 70 | + export type Flag = 'always' | 'gated' |
| 71 | + |
| 72 | + export interface Feature { |
| 73 | + [featureName: string]: { |
| 74 | + flags: Set<Flag>, |
| 75 | + aliasOf: Set<string>, |
| 76 | + dependencyOf: Set<string>, |
| 77 | + }, |
| 78 | + } |
| 79 | + |
| 80 | + export interface AliasesMap { |
| 81 | + all: string[], |
| 82 | + default: string[], |
| 83 | + es5: string[], |
| 84 | + es6: string[], |
| 85 | + es7: string[], |
| 86 | + es2015: string[], |
| 87 | + es2016: string[], |
| 88 | + es2017: string[], |
| 89 | + es2018: string[], |
| 90 | + es2019: string[], |
| 91 | + es2021: string[], |
| 92 | + [aliases: string]: string[], |
| 93 | + } |
| 94 | + |
| 95 | + /** |
| 96 | + * Get a list of all the aliases which exist within the collection of polyfill sources. |
| 97 | + * Returns a promise which resolves with an object mapping all the aliases within the collection |
| 98 | + * to the polyfills they include. |
| 99 | + */ |
| 100 | + export function listAliases (): Promise<AliasesMap> |
| 101 | + |
| 102 | + /** |
| 103 | + * Get a list of all the polyfills which exist within the collection of polyfill sources. |
| 104 | + * Returns a Promise which resolves with an array of all the polyfills within the collection. |
| 105 | + */ |
| 106 | + export function listAllPolyfills (): Promise<string[]> |
| 107 | + |
| 108 | + /** |
| 109 | + * Get the metadata for a specific polyfill within the collection of polyfill sources. |
| 110 | + * @param featureName - The name of a polyfill whose metadata should be returned. |
| 111 | + * Returns a Promise which resolves with the metadata or with undefined if no metadata exists |
| 112 | + * for the polyfill. |
| 113 | + */ |
| 114 | + export function describePolyfill (featureName: string): Promise<PolyfillMeta | undefined> |
| 115 | + |
| 116 | + /** |
| 117 | + * Create an options object for use with `getPolyfills` or `getPolyfillString`. |
| 118 | + * @param opts - Valid keys are uaString, minify, unknown, excludes, rum and features. |
| 119 | + * Returns an object which has merged `opts` with the defaults option values. |
| 120 | + */ |
| 121 | + export function getOptions (opts?: Options): Options |
| 122 | + |
| 123 | + /** |
| 124 | + * Given a set of features that should be polyfilled in 'opts.features' (with flags i.e. |
| 125 | + * `{<featurename>: {flags:Set[<flaglist>]}, ...}`), determine which have a |
| 126 | + * configuration valid for the given opts.uaString, and return a promise of set of canonical |
| 127 | + * (unaliased) features (with flags) and polyfills. |
| 128 | + * @param opts - Valid keys are uaString, minify, unknown, excludes, rum and features. |
| 129 | + * Returns a Promise which resolves to an Object which contains the canonicalised feature |
| 130 | + * definitions filtered for UA. |
| 131 | + */ |
| 132 | + export function getPolyfills (opts?: Options): Promise<Feature> |
| 133 | + |
| 134 | + /** |
| 135 | + * Create a polyfill bundle. |
| 136 | + * @param opts - Valid keys are uaString, minify, unknown, excludes, rum and features. |
| 137 | + * Returns a polyfill bundle as either a utf-8 ReadStream or as a Promise of a utf-8 String. |
| 138 | + */ |
| 139 | + export function getPolyfillString (opts?: Options): Promise<Readable | string> |
| 140 | + |
| 141 | +} |
0 commit comments