From be2fc3762cce6c8586376e04f93d5fecbc1597b7 Mon Sep 17 00:00:00 2001 From: Harris Lummis Date: Fri, 6 Jul 2018 09:39:38 -0700 Subject: [PATCH] [stampit] moved Stamp type to reside in main namespace (#26986) * UPDATE: moved Stamp type to within main exported namespace to allow access when imported * UPDATE: added tests for new format --- types/stampit/index.d.ts | 442 ++++++++++++++++----------------- types/stampit/stampit-tests.ts | 19 ++ 2 files changed, 240 insertions(+), 221 deletions(-) diff --git a/types/stampit/index.d.ts b/types/stampit/index.d.ts index def08b887d..87d96e4f4b 100644 --- a/types/stampit/index.d.ts +++ b/types/stampit/index.d.ts @@ -1,6 +1,7 @@ // Type definitions for stampit 3.0 // Project: https://github.com/stampit-org/stampit // Definitions by: Vasyl Boroviak +// Harris Lummis // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped /** @@ -11,12 +12,12 @@ type Init = (factoryArg: any, ctx?: Context) => any; /** * Composer function */ -type Composer = ({ stamp, composables }: { stamp: Stamp; composables: Composable[] }) => any; +type Composer = ({ stamp, composables }: { stamp: stampit.Stamp; composables: Composable[] }) => any; /** The stamp Descriptor */ interface Descriptor { /** Create a new stamp based on this descriptor */ - (...composables: Composable[]): Stamp; + (...composables: Composable[]): stampit.Stamp; /** * A hash containing methods (functions) of any future created instance. */ @@ -49,7 +50,7 @@ interface Descriptor { } /** Any composable object (stamp or descriptor) */ -type Composable = Stamp | Descriptor; +type Composable = stampit.Stamp | Descriptor; /** * The .init() function argument. @@ -63,7 +64,7 @@ interface Context { /** * The stamp the object has been instantiated with. */ - stamp: Stamp; + stamp: stampit.Stamp; /** * The arguments list passed to the stamp. @@ -132,231 +133,230 @@ interface Options { composers?: Composer[]; } -/** - * A factory function that will produce new objects using the - * prototypes that are passed in or composed. - */ -interface Stamp { - /** - * Invokes the stamp and returns a new object instance. - * @param state Properties you wish to set on the new objects. - * @param encloseArgs The remaining arguments are passed to all .enclose() functions. - * WARNING Avoid using two different .enclose() functions that expect different arguments. - * .enclose() functions that take arguments should not be considered safe to compose - * with other .enclose() functions that also take arguments. Taking arguments with - * an .enclose() function is an anti-pattern that should be avoided, when possible. - * @return A new object composed of the Stamps and prototypes provided. - */ - (state?: {}, ...encloseArgs: any[]): any; - - /** - * Just like calling stamp(), stamp.create() invokes the stamp and returns a new instance. - * @param state Properties you wish to set on the new objects. - * @param encloseArgs The remaining arguments are passed to all .enclose() functions. - * WARNING Avoid using two different .enclose() functions that expect different arguments. - * .enclose() functions that take arguments should not be considered safe to compose - * with other .enclose() functions that also take arguments. Taking arguments with - * an .enclose() function is an anti-pattern that should be avoided, when possible. - * @return A new object composed of the Stamps and prototypes provided. - */ - create(state?: {}, ...encloseArgs: any[]): any; - - /** - * Stamp metadata/composer function - */ - compose: Descriptor; - - /** - * Add methods to the methods prototype. Creates and returns new Stamp. Chainable. - * @param methods Object(s) containing map of method names and bodies for delegation. - * @return A new Stamp. - */ - methods(...methods: Array<{}>): Stamp; - - /** - * Take n objects and add them to the state prototype. Creates and returns new Stamp. Chainable. - * @param states Object(s) containing map of property names and values to clone for each new object. - * @return A new Stamp. - */ - refs(...states: Array<{}>): Stamp; - - /** - * Take a variable number of objects and shallow assign them to any future - * created instance of the Stamp. Creates and returns new Stamp. Chainable. - * @param objects Object(s) to shallow assign for each new object. - * @return A new Stamp. - */ - props(...objects: Array<{}>): Stamp; - - /** - * Take a variable number of objects and shallow assign them to any future - * created instance of the Stamp. Creates and returns new Stamp. Chainable. - * @param objects Object(s) to shallow assign for each new object. - * @return A new Stamp. - */ - properties(...objects: Array<{}>): Stamp; - - /** - * Take a variable number of objects and deeply merge them to any future - * created instance of the Stamp. Creates and returns a new Stamp. - * Chainable. - * @param deepObjects The object(s) to deeply merge for each new object - * @returns A new Stamp - */ - deepProps(...deepObjects: Array<{}>): Stamp; - - /** - * Take a variable number of objects and deeply merge them to any future - * created instance of the Stamp. Creates and returns a new Stamp. - * Chainable. - * @param deepObjects The object(s) to deeply merge for each new object - * @returns A new Stamp - */ - deepProperties(...deepObjects: Array<{}>): Stamp; - - /** - * @deprecated Use .init() instead. - */ - enclose(...functions: Init[]): Stamp; - - /** - * @deprecated Use .init() instead. - */ - enclose(...functions: Array<{}>): Stamp; - - /** - * Take in a variable number of functions and add them to the enclose - * prototype as initializers. - * @param functions Initializer functions used to create private data and - * privileged methods - * @returns A new stamp - */ - init(...functions: Init[]): Stamp; - - /** - * Take in a variable number of functions and add them to the enclose - * prototype as initializers. - * @param functions Initializer functions used to create private data and - * privileged methods - * @returns A new stamp - */ - init(functions: Init[]): Stamp; - - /** - * Take in a variable number of functions and add them to the enclose - * prototype as initializers. - * @param functions Initializer functions used to create private data and - * privileged methods - * @returns A new stamp - */ - initializers(...functions: Init[]): Stamp; - - /** - * Take in a variable number of functions and add them to the enclose - * prototype as initializers. - * @param functions Initializer functions used to create private data and - * privileged methods - * @returns A new stamp - */ - initializers(functions: Init[]): Stamp; - - /** - * Take n objects and add them to a new stamp and any future stamp it composes with. - * Creates and returns new Stamp. Chainable. - * @param statics Object(s) containing map of property names and values to mixin into each new stamp. - * @return A new Stamp. - */ - statics(...statics: Array<{}>): Stamp; - - /** - * Take n objects and add them to a new stamp and any future stamp it composes with. - * Creates and returns new Stamp. Chainable. - * @param statics Object(s) containing map of property names and values to mixin into each new stamp. - * @return A new Stamp. - */ - staticProperties(...statics: Array<{}>): Stamp; - - /** - * Deeply merge a variable number of objects and add them to a new stamp and - * any future stamp it composes. Creates and returns a new Stamp. Chainable. - * @param deepStatics The object(s) containing static properties to be - * merged - * @returns A new stamp - */ - deepStatics(...deepStatics: Array<{}>): Stamp; - - /** - * Deeply merge a variable number of objects and add them to a new stamp and - * any future stamp it composes. Creates and returns a new Stamp. Chainable. - * @param deepStatics The object(s) containing static properties to be - * merged - * @returns A new stamp - */ - staticDeepProperties(...deepStatics: Array<{}>): Stamp; - - /** - * Shallowly assign properties of Stamp arbitrary metadata and add them to - * a new stamp and any future Stamp it composes. Creates and returns a new - * Stamp. Chainable. - * @param confs The object(s) containing metadata properties - * @returns A new Stamp - */ - conf(...confs: Array<{}>): Stamp; - - /** - * Shallowly assign properties of Stamp arbitrary metadata and add them to - * a new stamp and any future Stamp it composes. Creates and returns a new - * Stamp. Chainable. - * @param confs The object(s) containing metadata properties - * @returns A new Stamp - */ - configuration(...confs: Array<{}>): Stamp; - - /** - * Deeply merge properties of Stamp arbitrary metadata and add them to a new - * Stamp and any future Stamp it composes. Creates and returns a new Stamp. - * Chainable. - * @param deepConfs The object(s) containing metadata properties - * @returns A new Stamp - */ - deepConf(...deepConfs: Array<{}>): Stamp; - - /** - * Deeply merge properties of Stamp arbitrary metadata and add them to a new - * Stamp and any future Stamp it composes. Creates and returns a new Stamp. - * Chainable. - * @param deepConfs The object(s) containing metadata properties - * @returns A new Stamp - */ - deepConfiguration(...deepConfs: Array<{}>): Stamp; - - /** - * Apply ES5 property descriptors to object instances created by the new - * Stamp returned by the function and any future Stamp it composes. Creates - * and returns a new stamp. Chainable. - * @param descriptors - * @returns A new Stamp - */ - propertyDescriptors(...descriptors: Array<{}>): Stamp; - - /** - * Apply ES5 property descriptors to a Stamp and any future Stamp it - * composes. Creates and returns a new stamp. Chainable. - * @param descriptors - * @returns A new Stamp - */ - staticPropertyDescriptors(...descriptors: Array<{}>): Stamp; -} - /** * Return a factory (aka Stamp) function that will produce new objects using the * prototypes that are passed in or composed. * @param options Stampit options object containing refs, methods, * init, props, statics, configurations, and property descriptors. */ -declare function stampit(options?: Options): Stamp; +declare function stampit(options?: Options): stampit.Stamp; declare namespace stampit { + /** + * A factory function that will produce new objects using the + * prototypes that are passed in or composed. + */ + interface Stamp { + /** + * Invokes the stamp and returns a new object instance. + * @param state Properties you wish to set on the new objects. + * @param encloseArgs The remaining arguments are passed to all .enclose() functions. + * WARNING Avoid using two different .enclose() functions that expect different arguments. + * .enclose() functions that take arguments should not be considered safe to compose + * with other .enclose() functions that also take arguments. Taking arguments with + * an .enclose() function is an anti-pattern that should be avoided, when possible. + * @return A new object composed of the Stamps and prototypes provided. + */ + (state?: {}, ...encloseArgs: any[]): any; + + /** + * Just like calling stamp(), stamp.create() invokes the stamp and returns a new instance. + * @param state Properties you wish to set on the new objects. + * @param encloseArgs The remaining arguments are passed to all .enclose() functions. + * WARNING Avoid using two different .enclose() functions that expect different arguments. + * .enclose() functions that take arguments should not be considered safe to compose + * with other .enclose() functions that also take arguments. Taking arguments with + * an .enclose() function is an anti-pattern that should be avoided, when possible. + * @return A new object composed of the Stamps and prototypes provided. + */ + create(state?: {}, ...encloseArgs: any[]): any; + + /** + * Stamp metadata/composer function + */ + compose: Descriptor; + + /** + * Add methods to the methods prototype. Creates and returns new Stamp. Chainable. + * @param methods Object(s) containing map of method names and bodies for delegation. + * @return A new Stamp. + */ + methods(...methods: Array<{}>): Stamp; + + /** + * Take n objects and add them to the state prototype. Creates and returns new Stamp. Chainable. + * @param states Object(s) containing map of property names and values to clone for each new object. + * @return A new Stamp. + */ + refs(...states: Array<{}>): Stamp; + + /** + * Take a variable number of objects and shallow assign them to any future + * created instance of the Stamp. Creates and returns new Stamp. Chainable. + * @param objects Object(s) to shallow assign for each new object. + * @return A new Stamp. + */ + props(...objects: Array<{}>): Stamp; + + /** + * Take a variable number of objects and shallow assign them to any future + * created instance of the Stamp. Creates and returns new Stamp. Chainable. + * @param objects Object(s) to shallow assign for each new object. + * @return A new Stamp. + */ + properties(...objects: Array<{}>): Stamp; + + /** + * Take a variable number of objects and deeply merge them to any future + * created instance of the Stamp. Creates and returns a new Stamp. + * Chainable. + * @param deepObjects The object(s) to deeply merge for each new object + * @returns A new Stamp + */ + deepProps(...deepObjects: Array<{}>): Stamp; + + /** + * Take a variable number of objects and deeply merge them to any future + * created instance of the Stamp. Creates and returns a new Stamp. + * Chainable. + * @param deepObjects The object(s) to deeply merge for each new object + * @returns A new Stamp + */ + deepProperties(...deepObjects: Array<{}>): Stamp; + + /** + * @deprecated Use .init() instead. + */ + enclose(...functions: Init[]): Stamp; + + /** + * @deprecated Use .init() instead. + */ + enclose(...functions: Array<{}>): Stamp; + + /** + * Take in a variable number of functions and add them to the enclose + * prototype as initializers. + * @param functions Initializer functions used to create private data and + * privileged methods + * @returns A new stamp + */ + init(...functions: Init[]): Stamp; + + /** + * Take in a variable number of functions and add them to the enclose + * prototype as initializers. + * @param functions Initializer functions used to create private data and + * privileged methods + * @returns A new stamp + */ + init(functions: Init[]): Stamp; + + /** + * Take in a variable number of functions and add them to the enclose + * prototype as initializers. + * @param functions Initializer functions used to create private data and + * privileged methods + * @returns A new stamp + */ + initializers(...functions: Init[]): Stamp; + + /** + * Take in a variable number of functions and add them to the enclose + * prototype as initializers. + * @param functions Initializer functions used to create private data and + * privileged methods + * @returns A new stamp + */ + initializers(functions: Init[]): Stamp; + + /** + * Take n objects and add them to a new stamp and any future stamp it composes with. + * Creates and returns new Stamp. Chainable. + * @param statics Object(s) containing map of property names and values to mixin into each new stamp. + * @return A new Stamp. + */ + statics(...statics: Array<{}>): Stamp; + + /** + * Take n objects and add them to a new stamp and any future stamp it composes with. + * Creates and returns new Stamp. Chainable. + * @param statics Object(s) containing map of property names and values to mixin into each new stamp. + * @return A new Stamp. + */ + staticProperties(...statics: Array<{}>): Stamp; + + /** + * Deeply merge a variable number of objects and add them to a new stamp and + * any future stamp it composes. Creates and returns a new Stamp. Chainable. + * @param deepStatics The object(s) containing static properties to be + * merged + * @returns A new stamp + */ + deepStatics(...deepStatics: Array<{}>): Stamp; + + /** + * Deeply merge a variable number of objects and add them to a new stamp and + * any future stamp it composes. Creates and returns a new Stamp. Chainable. + * @param deepStatics The object(s) containing static properties to be + * merged + * @returns A new stamp + */ + staticDeepProperties(...deepStatics: Array<{}>): Stamp; + + /** + * Shallowly assign properties of Stamp arbitrary metadata and add them to + * a new stamp and any future Stamp it composes. Creates and returns a new + * Stamp. Chainable. + * @param confs The object(s) containing metadata properties + * @returns A new Stamp + */ + conf(...confs: Array<{}>): Stamp; + + /** + * Shallowly assign properties of Stamp arbitrary metadata and add them to + * a new stamp and any future Stamp it composes. Creates and returns a new + * Stamp. Chainable. + * @param confs The object(s) containing metadata properties + * @returns A new Stamp + */ + configuration(...confs: Array<{}>): Stamp; + + /** + * Deeply merge properties of Stamp arbitrary metadata and add them to a new + * Stamp and any future Stamp it composes. Creates and returns a new Stamp. + * Chainable. + * @param deepConfs The object(s) containing metadata properties + * @returns A new Stamp + */ + deepConf(...deepConfs: Array<{}>): Stamp; + + /** + * Deeply merge properties of Stamp arbitrary metadata and add them to a new + * Stamp and any future Stamp it composes. Creates and returns a new Stamp. + * Chainable. + * @param deepConfs The object(s) containing metadata properties + * @returns A new Stamp + */ + deepConfiguration(...deepConfs: Array<{}>): Stamp; + + /** + * Apply ES5 property descriptors to object instances created by the new + * Stamp returned by the function and any future Stamp it composes. Creates + * and returns a new stamp. Chainable. + * @param descriptors + * @returns A new Stamp + */ + propertyDescriptors(...descriptors: Array<{}>): Stamp; + + /** + * Apply ES5 property descriptors to a Stamp and any future Stamp it + * composes. Creates and returns a new stamp. Chainable. + * @param descriptors + * @returns A new Stamp + */ + staticPropertyDescriptors(...descriptors: Array<{}>): Stamp; + } /** * A shortcut methods for stampit().methods() * @param methods Object(s) containing map of method names and bodies for delegation. diff --git a/types/stampit/stampit-tests.ts b/types/stampit/stampit-tests.ts index 410e2d2218..5b7c41109a 100644 --- a/types/stampit/stampit-tests.ts +++ b/types/stampit/stampit-tests.ts @@ -142,3 +142,22 @@ t.thing; // 'initialized', t.foo(); // 'foo', t.bar(); // 'bar' + +interface SomeStampInstance { + a: string; + b: string; +} + +// Test import of stamp type +interface SomeStamp extends stampit.Stamp { + (params: { a: number; b: boolean}): SomeStampInstance; +} + +const SomeStamp = stampit() + .init((params: { a: number; b: boolean}) => { + this.a = '' + a; + this.b = '' + b; + }) as SomeStamp; + +SomeStamp({ a: 1, b: false }); // $ExpectType SomeStampInstance +SomeStamp({ a: 1, b: false }).a; // $ExpectType string