diff --git a/mw/Map.d.ts b/mw/Map.d.ts index 14e64c9..707dcb0 100644 --- a/mw/Map.d.ts +++ b/mw/Map.d.ts @@ -1,7 +1,64 @@ -type KeyOrArray = keyof T | Array; -type GetOrDefault = V extends Required> ? V[K] : Required[K] | T; -type PickOrDefault, T> = - S extends Array ? {[K in SS & keyof V]-?: GetOrDefault} : GetOrDefault; +type TypeOrArray = T | T[]; + +// Get/PickOrDefault extracts values from V using key selection S +// - TD is the value type of missing properties +// - TX is the value type of unknown properties + +type GetOrDefault = K extends keyof V + ? V extends Required> + ? V[K] + : Required[K] | TD + : TX | TD; + +type PickOrDefault, TD, TX = unknown> = + S extends Array + ? {[P in K & PropertyKey]-?: GetOrDefault} + : GetOrDefault; + +// `ExtensibleMap` is an alternative to `Map` +// but unlike the latter, ExtensibleMap provides additional overloads to improve selection +// autocompletion and type checking. + +export interface ExtensibleMap, TX = unknown> extends mw.Map { + /** + * Check if a given key exists in the map. + * + * @param selection Key to check + * @returns True if the key exists + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-exists + */ + exists(selection: S): selection is S; + exists(selection: S): selection is S; + + /** + * Get the value of one or more keys. + * + * If called with no arguments, all values are returned. + * + * @param selection Key or array of keys to retrieve values for. + * @param fallback Value for keys that don't exist. + * @returns If selection was a string, returns the value. If selection was an array, returns + * an object of key/values. If no selection is passed, a new object with all key/values is returned. + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-get + */ + get, TD>(selection: S, fallback: TD): PickOrDefault; + get, TD>(selection: S, fallback: TD): PickOrDefault; + get>(selection: S): PickOrDefault; + get>(selection: S): PickOrDefault; + get = V | Record>(): T; + + /** + * Set the value of one or more keys. + * + * @param selection Key to set value for, or object mapping keys to values + * @param value Value to set (optional, only in use when key is a string) + * @returns True on success, false on failure + * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-set + */ + set(selection: S, value: V[S]): boolean; + set(selection: S, value: TX): boolean; + set & Record>(selection: S): boolean; +} declare global { namespace mw { @@ -40,9 +97,9 @@ declare global { * an object of key/values. If no selection is passed, a new object with all key/values is returned. * @see https://doc.wikimedia.org/mediawiki-core/master/js/#!/api/mw.Map-method-get */ - get, T>(selection: S, fallback: T): PickOrDefault; - get>(selection: S): PickOrDefault; - get(): S; + get, TD>(selection: S, fallback: TD): PickOrDefault; + get>(selection: S): PickOrDefault; + get(): T; /** * Set the value of one or more keys.