Create build types package (#65)

* Move middlewarestack interface to @aws/types

* Add configuration types

* Create a package to house types used at build time but not at runtime and relocate model parser types there

Author: jeskew

packages/middleware-stack/src/index.ts

@@ -1,6 +1,8 @@
 import {
     Handler,
+    HandlerOptions,
     Middleware,
+    MiddlewareStack as IMiddlewareStack,
     HandlerExecutionContext,
 } from '@aws/types';
 
@@ -15,69 +17,12 @@ interface HandlerListEntry<
     tags?: Set<string>;
 }
 
-export interface HandlerOptions {
-    /**
-     * Handlers are ordered using a "step" that describes the stage of command
-     * execution at which the handler will be executed. The available steps are:
-     *
-     * - initialize: The input is being prepared and validated. Examples of
-     *      typical initialization tasks include injecting default options and
-     *      parameter validation.
-     * - build: The input is being serialized into an HTTP request. The input
-     *      should not be altered in middleware occupying this step, as it may
-     *      have already been serialized into a request. Examples of typical
-     *      build tasks include request construction and injecting HTTP headers.
-     * - finalize: The request is being prepared to be sent over the wire. The
-     *      request in this stage should already be semantically complete and
-     *      should therefore only be altered as match the recipient's
-     *      expectations. Examples of typical finalization tasks include request
-     *      signing and injecting hop-by-hop headers.
-     *
-     *      Unlike initialization and build handlers, which are executed once
-     *      per operation execution, finalization handlers will be executed for
-     *      each HTTP request sent.
-     *
-     * @default 'build'
-     */
-    step?: Step;
-
-    /**
-     * A number that specifies how early in a given step of the middleware stack
-     * a handler should be executed. Higher numeric priorities will be executed
-     * earlier.
-     *
-     * @default 0
-     */
-    priority?: number;
-
-    /**
-     * A set of strings that identify the general purpose or important
-     * characteristics of a given handler.
-     */
-    tags?: Set<string>;
-}
-
-/**
- * Builds a single handler function from zero or more middleware classes and a
- * core handler. The core handler is meant to send command objects to AWS
- * services and return promises that will resolve with the operation result or
- * be rejected with an error.
- *
- * When a composed handler is invoked, the arguments will pass through all
- * middleware in a defined order, and the return from the innermost handler will
- * pass through all middleware in the reverse of that order.
- */
-export class MiddlewareStack<T extends Handler<any, any>> {
+export class MiddlewareStack<T extends Handler<any, any, any>> implements
+    IMiddlewareStack<T>
+{
     private readonly entries: Array<HandlerListEntry<T>> = [];
     private sorted: boolean = false;
 
-    /**
-     * Add middleware to the list, optionally specifying a step, priority, and
-     * tags.
-     *
-     * Middleware registered at the same step and with the same priority may be
-     * executed in any order.
-     */
     add(
         middleware: Middleware<T>,
         {
@@ -95,21 +40,12 @@ export class MiddlewareStack<T extends Handler<any, any>> {
         });
     }
 
-    /**
-     * Create a shallow clone of this list. Step bindings and handler priorities
-     * and tags are preserved in the copy.
-     */
     clone(): MiddlewareStack<T> {
         const clone = new MiddlewareStack<T>();
         clone.entries.push(...this.entries);
         return clone;
     }
 
-    /**
-     * Create a list containing the middlewares in this list as well as the
-     * middlewares in the `from` list. Neither source is modified, and step
-     * bindings and handler priorities and tags are preserved in the copy.
-     */
     concat(
         from: MiddlewareStack<T>
     ): MiddlewareStack<T> {
@@ -118,14 +54,6 @@ export class MiddlewareStack<T extends Handler<any, any>> {
         return clone;
     }
 
-    /**
-     * Removes middleware from the stack.
-     *
-     * If a string is provided, any entry in the stack whose tags contain that
-     * string will be removed from the stack.
-     *
-     * If a middleware class is provided, all usages thereof will be removed.
-     */
     remove(toRemove: Middleware<T>|string): boolean {
         const {length} = this.entries;
         if (typeof toRemove === 'string') {
@@ -137,16 +65,6 @@ export class MiddlewareStack<T extends Handler<any, any>> {
         return this.entries.length < length;
     }
 
-    /**
-     * Builds a single handler function from zero or more middleware classes and
-     * a core handler. The core handler is meant to send command objects to AWS
-     * services and return promises that will resolve with the operation result
-     * or be rejected with an error.
-     *
-     * When a composed handler is invoked, the arguments will pass through all
-     * middleware in a defined order, and the return from the innermost handler
-     * will pass through all middleware in the reverse of that order.
-     */
     resolve(handler: T, context: HandlerExecutionContext): T {
         if (!this.sorted) {
             this.sort();

packages/types/src/configuration.ts

@@ -0,0 +1,58 @@
+import {MiddlewareStack, Step} from './middleware';
+
+export type ConfigurationPropertyType = 'transient'|'persistent';
+
+export interface ConfigurationPropertyDefinition<
+    InputType,
+    ServiceConfiguration extends {[key: string]: any}
+> {
+    /**
+     * The type of configuration property represented by this key.
+     *
+     * Transient properties are used during client construction, typically as
+     * inputs to other configuration properties.
+     *
+     * Persistent properties will be stored on the `config` property of a
+     * constructed client and will be used while executing methods.
+     */
+    type: ConfigurationPropertyType;
+
+    /**
+     * Whether this property must be supplied by the user of a client. If value
+     * must be resolved but a default is available, this property should be
+     * `false`.
+     */
+    required: boolean;
+
+    /**
+     * A static value to use as the default should none be supplied.
+     */
+    defaultValue?: InputType;
+
+    /**
+     * A function that returns a default value for this property. It will be
+     * called if no value is supplied.
+     */
+    defaultProvider?: {
+        (config: ServiceConfiguration): InputType;
+    }
+
+    /**
+     * A function that finalizes the value supplied and/or alters the client
+     * configuration or middleware stack in reaction to it.
+     */
+    apply?: {
+        (
+            value: InputType,
+            config: ServiceConfiguration,
+            clientMiddlewareStack: MiddlewareStack<any>
+        ): void;
+    }
+}
+
+/**
+ * A map of configuration property names to configuration property definitions.
+ */
+export type ConfigurationDefinition<T extends {[key: string]: any}> = {
+    readonly [P in keyof T]: ConfigurationPropertyDefinition<P, T>;
+};

packages/types/src/index.ts

@@ -1,4 +1,5 @@
 export * from './abort';
+export * from './configuration';
 export * from './credentials';
 export * from './crypto';
 export * from './http';

packages/types/src/middleware.ts

@@ -43,7 +43,7 @@ export interface Handler<
 /**
  * A constructor for a class that implements the {Handler} interface.
  */
-export interface Middleware<T extends Handler<any, any>> {
+export interface Middleware<T extends Handler<any, any, any>> {
     /**
      * @param next The handler to invoke after this middleware has operated on
      * the user input and before this middleware operates on the output.
@@ -56,6 +56,96 @@ export interface Middleware<T extends Handler<any, any>> {
     ): T;
 }
 
+export type Step = 'initialize'|'build'|'finalize';
+
+export interface HandlerOptions {
+    /**
+     * Handlers are ordered using a "step" that describes the stage of command
+     * execution at which the handler will be executed. The available steps are:
+     *
+     * - initialize: The input is being prepared and validated. Examples of
+     *      typical initialization tasks include injecting default options and
+     *      parameter validation.
+     * - build: The input is being serialized into an HTTP request. The input
+     *      should not be altered in middleware occupying this step, as it may
+     *      have already been serialized into a request. Examples of typical
+     *      build tasks include request construction and injecting HTTP headers.
+     * - finalize: The request is being prepared to be sent over the wire. The
+     *      request in this stage should already be semantically complete and
+     *      should therefore only be altered as match the recipient's
+     *      expectations. Examples of typical finalization tasks include request
+     *      signing and injecting hop-by-hop headers.
+     *
+     *      Unlike initialization and build handlers, which are executed once
+     *      per operation execution, finalization handlers will be executed for
+     *      each HTTP request sent.
+     *
+     * @default 'build'
+     */
+    step?: Step;
+
+    /**
+     * A number that specifies how early in a given step of the middleware stack
+     * a handler should be executed. Higher numeric priorities will be executed
+     * earlier.
+     *
+     * @default 0
+     */
+    priority?: number;
+
+    /**
+     * A set of strings that identify the general purpose or important
+     * characteristics of a given handler.
+     */
+    tags?: Set<string>;
+}
+
+export interface MiddlewareStack<T extends Handler<any, any, any>> {
+    /**
+     * Add middleware to the list, optionally specifying a step, priority, and
+     * tags.
+     *
+     * Middleware registered at the same step and with the same priority may be
+     * executed in any order.
+     */
+    add(middleware: Middleware<T>, options?: HandlerOptions): void;
+
+    /**
+     * Create a shallow clone of this list. Step bindings and handler priorities
+     * and tags are preserved in the copy.
+     */
+    clone(): MiddlewareStack<T>;
+
+    /**
+     * Create a list containing the middlewares in this list as well as the
+     * middlewares in the `from` list. Neither source is modified, and step
+     * bindings and handler priorities and tags are preserved in the copy.
+     */
+    concat(from: MiddlewareStack<T>): MiddlewareStack<T>;
+
+    /**
+     * Removes middleware from the stack.
+     *
+     * If a string is provided, any entry in the stack whose tags contain that
+     * string will be removed from the stack.
+     *
+     * If a middleware class is provided, all usages thereof will be removed.
+     */
+    remove(toRemove: Middleware<T>|string): boolean;
+
+    /**
+     * Builds a single handler function from zero or more middleware classes and
+     * a core handler. The core handler is meant to send command objects to AWS
+     * services and return promises that will resolve with the operation result
+     * or be rejected with an error.
+     *
+     * When a composed handler is invoked, the arguments will pass through all
+     * middleware in a defined order, and the return from the innermost handler
+     * will pass through all middleware in the reverse of that order.
+     */
+    resolve(handler: T, context: HandlerExecutionContext): T;
+}
+
 /**
  * Data and helper objects that are not expected to change from one execution of
  * a composed handler to another.