@alterior/runtime 3.5.3 → 3.5.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alterior/runtime",
-  "version": "3.5.3",
+  "version": "3.5.6",
   "description": "Core runtime for Alterior apps",
   "author": "The Alterior Project (https://github.com/alterior-mvc)",
   "license": "MIT",
@@ -37,14 +37,15 @@
     "docs": "typedoc ."
   },
   "dependencies": {
-    "@alterior/annotations": "^3.4.0",
+    "@alterior/annotations": "^3.5.6",
     "@alterior/common": "^3.4.0",
-    "@alterior/di": "^3.5.3",
+    "@alterior/di": "^3.5.6",
     "tslib": "^2.3.1"
   },
   "peerDependencies": {
     "reflect-metadata": "^0.1.13",
     "zone.js": "^0.11.4"
   },
-  "gitHead": "808d85ec078d91261d8388c717d77c02aefc568a"
+  "lernaKick": 1,
+  "gitHead": "220e169fc8c855dc0935620bdb5efb1e9a2b86a7"
 }

package/src/app-options.ts

@@ -0,0 +1,72 @@
+import { Annotation, AnnotationDecorator, MetadataName } from '@alterior/annotations';
+
+export interface ApplicationOptions {
+	
+	/**
+	 * Specify a human readable name for your application.
+	 */
+	name? : string;
+
+	/**
+	 * Version of the service
+	 */
+	version? : string;
+	
+	/**
+	 * The computer-readable name for your application. Should match your NPM package name.
+	 */
+	packageName? : string;
+
+	/**
+	 * A long-form description for your application, when necessary. If you implement only one,
+	 * implement summary instead.
+	 */
+	description? : string;
+
+	/**
+	 * A shorter-form description for your application, when necessary. If you implement only one,
+	 * implement this instead of description.
+	 */
+	summary? : string;
+
+	/**
+	 * A set of string tags related to your application.
+	 */
+	tags? : string[];
+
+	group? : string;
+	
+	/**
+	 * Enable verbose console logging for Alterior
+	 */
+	verbose? : boolean;
+
+	/**
+	 * Whether to start the service immediately on startup.
+	 * Defaults to true.
+	 */
+	autostart? : boolean;
+
+	/**
+	 * Turn off all console output
+	 */
+	silent? : boolean;
+}
+
+/**
+ * Used to attach an ApplicationOptions object onto a class definition.
+ */
+@MetadataName('@alterior/di:Application')
+export class AppOptionsAnnotation extends Annotation {
+	constructor(readonly options? : ApplicationOptions) {
+		super();
+	}
+}
+
+/**
+ * Use this decorator to define the options for your application, 
+ * either on the entry module, or service class when using `@alterior/web-server`.
+ */
+export const AppOptions = AppOptionsAnnotation.decorator({
+	validTargets: ['class']
+});

package/src/application.ts

@@ -0,0 +1,207 @@
+import 'reflect-metadata';
+
+import { ApplicationOptions, AppOptionsAnnotation } from './app-options';
+import { ReflectiveInjector, Provider, Injectable, 
+		 ModuleAnnotation, Injector } from '@alterior/di';
+import { Runtime } from './modules';
+import { ApplicationArgs } from './args';
+import { RolesService } from './roles.service';
+import { Environment, Time } from '@alterior/common';
+
+declare let module : never;
+
+export class ApplicationOptionsRef {
+	constructor(
+		options : ApplicationOptions
+	) {
+		this.options = Object.assign({}, options);
+	}
+
+	readonly options : ApplicationOptions;
+}
+
+/**
+ * Represents the current runtime execution context.
+ * This is exposed via a zone-local variable, and the Runtime
+ * populates it with useful information as it becomes available.
+ */
+export class ExecutionContext {
+	/**
+	 * Retrieve the Alterior application which is currently being executed.
+	 * If an application has not been bootstrapped yet, the value is null.
+	 */
+	public application : Application = null;
+
+	static readonly ZONE_LOCAL_NAME  = '@alterior/runtime:ExecutionContext';
+
+	/**
+	 * Get the current execution context, if any.
+	 */
+	public static get current(): ExecutionContext {
+		return Zone.current.get(ExecutionContext.ZONE_LOCAL_NAME);
+	}
+
+	/**
+	 * Execute the given function in a new zone which has
+	 * this ExecutionContext instance as the current execution context.
+	 */
+	public async run<T>(callback : () => Promise<T>): Promise<T> {
+		let zone = Zone.current.fork({
+			name: `AlteriorExecutionContext`,
+			properties: {
+				[ExecutionContext.ZONE_LOCAL_NAME]: this
+			}
+		});
+
+		return await zone.run(() => callback());
+	}
+
+	public runSync<T>(callback : () => T): T {
+		let zone = Zone.current.fork({
+			name: `AlteriorExecutionContext`,
+			properties: {
+				[ExecutionContext.ZONE_LOCAL_NAME]: this
+			}
+		});
+
+		return zone.run(() => callback());
+	}
+}
+
+/**
+ * Handles bootstrapping the application.
+ */
+@Injectable()
+export class Application {
+	constructor(
+		readonly runtime? : Runtime,
+		private _optionsRef? : ApplicationOptionsRef,
+		private _args? : ApplicationArgs
+	) {
+
+	}
+
+	public start() {
+		this.runtime.start();
+	}
+
+	public stop() {
+		this.runtime.stop();
+	}
+
+	get injector() {
+		return this.runtime.injector;
+	}
+
+	inject<T>(ctor : { new(...args) : T }, notFoundValue? : T): T {
+		return this.injector.get(ctor, notFoundValue);
+	}
+
+	get args() : string[] {
+		return this._args.get();
+	}
+
+	get options() : ApplicationOptions {
+		return this._optionsRef.options;
+	}
+
+	private static loadOptions(entryModule : Function, bootstrapOptions : ApplicationOptions): ApplicationOptions {
+		// Read an @AppOptions() decorator if any, and merge providers from it 
+		// into the bootstrapped providers
+
+		let appOptionsAnnotation = AppOptionsAnnotation.getForClass(entryModule);
+		let appProvidedOptions : ApplicationOptions = appOptionsAnnotation ? appOptionsAnnotation.options : {} || {};
+		
+		return Object.assign(
+			<ApplicationOptions>{
+				version: '0.0.0',
+				verbose: false,
+				silent: false,
+				autostart: true,
+				providers: []
+			}, 
+			appProvidedOptions, 
+			bootstrapOptions
+		);
+	}
+
+	private static validateEntryModule(module : Function) {
+		if (typeof module !== 'function') {
+			throw new Error(
+				`You must pass a Module class as the first parameter ` 
+				+ `to bootstrap(). You provided: ` 
+				+ `${typeof module} with value '${module}'`
+			);
+		}
+	
+		let moduleMetadata = ModuleAnnotation.getForClass(module);
+		if (!moduleMetadata)
+			throw new Error(`You must pass a module class decorated by @Module()`);
+	}
+
+	private _bootstrapped : boolean = false;
+
+	/**
+	 * Bootstrap an Alterior application.
+	 */
+	public static bootstrap(entryModule : Function, options? : ApplicationOptions): Application {
+		let executionContext = new ExecutionContext();
+		return executionContext.runSync(() => {
+			this.validateEntryModule(entryModule);
+
+			options = this.loadOptions(entryModule, options);
+	
+			let runtime = new Runtime(entryModule);
+
+			let providers : Provider[] = [
+				ApplicationArgs,
+				RolesService,
+				Environment,
+				Time
+			];
+	
+			runtime.contributeProviders(providers);
+			providers.push(
+				{
+					provide: ApplicationOptionsRef,
+					useValue: new ApplicationOptionsRef(options)
+				}
+			);
+			providers.push(Application);
+
+			runtime.providers = providers;
+	
+			let injector : ReflectiveInjector;
+			try {
+				injector = ReflectiveInjector.resolveAndCreate(providers);
+			} catch (e) {
+				console.error(`Failed to resolve injector:`);
+				console.error(e);
+				console.error(`Providers:`);
+				console.dir(providers);
+				console.error(`Modules:`);
+				console.dir(runtime.definitions);
+				throw e;
+			}
+
+			(<RolesService>injector.get(RolesService)).silent = options.silent;
+			
+			runtime.load(injector);
+			executionContext.application = runtime.getService(Application);
+			
+			runtime.fireEvent('OnInit');
+			runtime.configure();
+	
+			if (runtime.selfTest) {
+				console.log(`[Self Test] ✔ Looks good!`);
+				process.exit(0);
+			}
+			
+			if (options.autostart)
+				runtime.start();
+
+			return executionContext.application;
+		});
+	}
+	
+}

package/src/args.ts

@@ -0,0 +1,9 @@
+/**
+ * Abstracts the fetching of the application's arguments. This is most useful for testing,
+ * but could also be used if trying to host Alterior in a strange environment.
+ */
+export class ApplicationArgs {
+	public get() {
+		return process.argv.slice(2);
+	}
+}

package/src/expose.ts

@@ -0,0 +1,46 @@
+import { shallowClone } from '@alterior/common';
+
+export interface ExposeOptions {
+    
+}
+
+export interface Exposure {
+    propertyName: string;
+}
+
+export const EXPOSURES_PROPERTY = 'alterior:service:exposures';
+
+export function Expose() {
+    return function (target: Object, propertyName: string, descriptor: PropertyDescriptor) {
+		if (!target.hasOwnProperty(EXPOSURES_PROPERTY)) {
+			Object.defineProperty(target, EXPOSURES_PROPERTY, {
+				enumerable: false,
+				value: []
+			});
+		}
+
+		let routes = target[EXPOSURES_PROPERTY] || [];
+		routes.push(<Exposure>{
+			propertyName
+		});
+	};
+}
+
+
+export class ExposureReflector {
+	constructor(type : Function) {
+		this.exposures = this.getExposuresFromType(type).map(x => shallowClone(x));
+	}
+
+	private getExposuresFromType(type : Function) {
+		let parentPrototype = Object.getPrototypeOf(type.prototype);
+		let exposures : Exposure[] = (type.prototype[EXPOSURES_PROPERTY] || []);
+		if (parentPrototype) {
+			return [].concat(...this.getExposuresFromType(parentPrototype.constructor), ...exposures);
+		} else {
+			return [].concat(...exposures);
+		}
+	}
+
+	public exposures : Exposure[];
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './app-options';
+export * from './lifecycle';
+export * from './args';
+export * from './application';
+export * from './modules';
+export * from './reflector';
+export * from './roles.service';
+export * from './service';
+export * from './expose';

package/src/lifecycle.ts

@@ -0,0 +1,26 @@
+/**
+ * Specifies that the implementer understands the Alterior OnInit lifecycle event.
+ * Implementing this interface is a best practice to ensure that implementations 
+ * are well-formed.
+ */
+export interface OnInit {
+	altOnInit(); 
+}
+
+/**
+ * Specifies that the implementer understands the Alterior OnStart lifecycle event. 
+ * Implementing this interface is a best practice to ensure that implementations 
+ * are well-formed.
+ */
+export interface OnStart {
+	altOnStart(); 
+}
+
+/**
+ * Specifies that the implementer understands the Alterior OnStop lifecycle event.
+ * Implementing this interface is a best practice to ensure that implementations 
+ * are well-formed.
+ */
+export interface OnStop {
+	altOnStop(); 
+}