@arkstack/contract 0.5.1 → 0.5.3

package/README.md

@@ -1,5 +1,7 @@
 # @arkstack/contract
 
+[![@arkstack/contract](https://img.shields.io/npm/dt/@arkstack/contract?style=flat-square&label=@arkstack/contract&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F@arkstack/contract)](https://www.npmjs.com/package/@arkstack/contract)
+
 Contract module for Arkstack, providing shared interfaces and type contracts used across the framework.
 
 This package defines the shared shape each framework driver must implement.

package/dist/global.d.ts

@@ -1,9 +1,25 @@
-import { ArkstackRouterAwareCore } from './index'
+import { Arkstack } from '.'
 
 declare global {
-  function app (): ArkstackRouterAwareCore<never, never>
+  function app (): Arkstack<never, never>
   var arkctx: {
     runtime: 'CLI' | 'HTTP' | 'Worker'
     command?: string
   }
+}
+
+declare module '@arkstack/common' {
+  interface HookRegistry {
+    'set:root-dir': {
+      after: (dir: string) => void
+    }
+  }
+}
+
+declare module '@arkstack/foundry' {
+  interface HookRegistry {
+    'set:root-dir': {
+      after: (dir: string) => void
+    }
+  }
 }

package/dist/index.d.ts

@@ -1,22 +1,16 @@
 /// <reference path="./global.d.ts" />
-//#region src/index.d.ts
-type PromiseOrValue<T> = T | Promise<T>;
+//#region src/http.d.ts
 interface ArkstackMiddlewareConfig<TMiddleware> {
   global: TMiddleware[];
   before: TMiddleware[];
   after: TMiddleware[];
 }
-interface ArkstackRouteListOptions {
-  path?: string;
-}
-interface ArkstackRouterContract<TApp, TRoutes = unknown> {
-  bind(app: TApp): PromiseOrValue<unknown>;
-  list(options?: ArkstackRouteListOptions, app?: TApp): PromiseOrValue<TRoutes>;
-}
-interface ArkstackRouterAwareCore<TApp, TRoutes = unknown> {
-  getAppInstance(): TApp;
-  getRouter(): ArkstackRouterContract<TApp, TRoutes>;
-}
+//#endregion
+//#region src/kits.d.ts
+/**
+ * The ArkstackKitDriver class defines the contract for a driver
+ * that can be used with the ArkstackKitContract.
+ */
 declare abstract class ArkstackKitDriver<TApp, TMiddleware> {
   abstract readonly name: string;
   abstract createApp(): TApp;
@@ -27,6 +21,10 @@ declare abstract class ArkstackKitDriver<TApp, TMiddleware> {
   registerErrorHandler(_app: TApp): PromiseOrValue<void>;
   abstract start(app: TApp, port: number): PromiseOrValue<void>;
 }
+/**
+ * The ArkstackKitContract class defines the contract for an
+ * application that uses the ArkstackKitDriver.
+ */
 declare abstract class ArkstackKitContract<TApp, TMiddleware> {
   abstract app: TApp;
   abstract driver: ArkstackKitDriver<TApp, TMiddleware>;
@@ -35,5 +33,96 @@ declare abstract class ArkstackKitContract<TApp, TMiddleware> {
   abstract shutdown(): Promise<void>;
 }
 //#endregion
-export { ArkstackKitContract, ArkstackKitDriver, ArkstackMiddlewareConfig, ArkstackRouteListOptions, ArkstackRouterAwareCore, ArkstackRouterContract, PromiseOrValue };
-//# sourceMappingURL=index.d.ts.map
+//#region src/routing.d.ts
+interface ArkstackRouteListOptions {
+  path?: string;
+}
+interface ArkstackRouterContract<TApp, TRoutes = unknown> {
+  bind(app: TApp): PromiseOrValue<unknown>;
+  list(options?: ArkstackRouteListOptions, app?: TApp): PromiseOrValue<TRoutes>;
+}
+//#endregion
+//#region src/Arkstack.d.ts
+type PromiseOrValue<T> = T | Promise<T>;
+type ENV = 'development' | 'production' | 'stagging' | 'testing';
+type RootDirChangeListener = (dir: string, previousDir: string) => void;
+declare abstract class Arkstack<TApp, TRoutes = unknown, THandler = unknown> {
+  static app: unknown;
+  private static appRootDir;
+  protected app: TApp;
+  protected driver: ArkstackKitDriver<TApp, THandler>;
+  abstract getRouter(): ArkstackRouterContract<TApp, TRoutes>;
+  /**
+   * Boots the application by mounting public assets, binding the
+   * router, applying middleware, and starting the server.
+   *
+   * @param port      The numeric port to run the server on
+   * @param defer     Set to true to skip server startup
+   */
+  abstract boot(port: number, defer?: boolean): Promise<void>;
+  /**
+   * Gets the driver application instance.
+   *
+   * @returns
+   */
+  getAppInstance(): TApp;
+  /**
+   * Gets the static driver application instance.
+   *
+   * @returns
+   */
+  static getAppInstance<TApp = unknown>(): TApp;
+  /**
+   * Gets the ArkstackKitDriver instance used by the application.
+   *
+   * @returns
+   */
+  getDriver(): ArkstackKitDriver<TApp, THandler>;
+  /**
+   * Boostrap the app and start up the server
+   *
+   * @param defaultPort   start the server with this port if neither PORT nor APP_PORT env variable is set
+   * @param defer         Set to true to skip server startup
+   */
+  startup(defaultPort?: number, defer?: boolean): Promise<void>;
+  /**
+   * Shuts down the application by disconnecting from the database and exiting the process.
+   */
+  shutdown(): Promise<void>;
+  /**
+   * Get the current app root directory
+   *
+   * @alias getRootDir()
+   * @returns
+   */
+  static rootDir(): string;
+  /**
+   * Get the current app root directory
+   *
+   * @alias getRootDir()
+   * @returns
+   */
+  rootDir(): string;
+  /**
+   * Get the current app root directory
+   *
+   * @returns
+   */
+  static getRootDir(): string;
+  /**
+   * Set the current app root directory
+   *
+   * @param dir   The prefered app root directory
+   * @returns
+   */
+  setRootDir(dir: string): void;
+  /**
+   * Set the current app root directory
+   *
+   * @param dir   The prefered app root directory
+   * @returns
+   */
+  static setRootDir(dir: string): void;
+}
+//#endregion
+export { Arkstack, ArkstackKitContract, ArkstackKitDriver, ArkstackMiddlewareConfig, ArkstackRouteListOptions, ArkstackRouterContract, ENV, PromiseOrValue, RootDirChangeListener };

package/dist/index.js

@@ -1,4 +1,102 @@
-//#region src/index.ts
+import { Hook } from "@arkstack/foundry";
+//#region src/Arkstack.ts
+var Arkstack = class Arkstack {
+	static app;
+	static appRootDir = process.cwd();
+	app;
+	driver;
+	/**
+	* Gets the driver application instance.
+	* 
+	* @returns 
+	*/
+	getAppInstance() {
+		return this.app;
+	}
+	/**
+	* Gets the static driver application instance.
+	* 
+	* @returns 
+	*/
+	static getAppInstance() {
+		return Arkstack.app;
+	}
+	/**
+	* Gets the ArkstackKitDriver instance used by the application.
+	* 
+	* @returns 
+	*/
+	getDriver() {
+		return this.driver;
+	}
+	/**
+	* Boostrap the app and start up the server
+	* 
+	* @param defaultPort   start the server with this port if neither PORT nor APP_PORT env variable is set
+	* @param defer         Set to true to skip server startup
+	*/
+	async startup(defaultPort = 3e3, defer) {
+		const { bootWithDetectedPort } = await import("@arkstack/common");
+		await bootWithDetectedPort(async (port) => {
+			await this.boot(port, defer);
+		}, Number(process.env.PORT ?? process.env.APP_PORT ?? defaultPort), this, defer);
+	}
+	/**
+	* Shuts down the application by disconnecting from the database and exiting the process.
+	*/
+	async shutdown() {
+		process.exit(0);
+	}
+	/**
+	* Get the current app root directory
+	* 
+	* @alias getRootDir()
+	* @returns
+	*/
+	static rootDir() {
+		return Arkstack.appRootDir;
+	}
+	/**
+	* Get the current app root directory
+	* 
+	* @alias getRootDir()
+	* @returns
+	*/
+	rootDir() {
+		return Arkstack.appRootDir;
+	}
+	/**
+	* Get the current app root directory
+	* 
+	* @returns
+	*/
+	static getRootDir() {
+		return Arkstack.appRootDir;
+	}
+	/**
+	* Set the current app root directory
+	* 
+	* @param dir   The prefered app root directory
+	* @returns
+	*/
+	setRootDir(dir) {
+		Arkstack.setRootDir(dir);
+	}
+	/**
+	* Set the current app root directory
+	* 
+	* @param dir   The prefered app root directory
+	* @returns
+	*/
+	static setRootDir(dir) {
+		const previousDir = Arkstack.appRootDir;
+		Arkstack.appRootDir = dir;
+		if (previousDir === dir) return;
+		if (Hook.has("set:root-dir", "after")) Hook.get("set:root-dir", "after", dir);
+	}
+};
+//#endregion
+//#region src/kits.ts
 /**
 * The ArkstackKitDriver class defines the contract for a driver 
 * that can be used with the ArkstackKitContract. 
@@ -12,6 +110,4 @@ var ArkstackKitDriver = class {
 */
 var ArkstackKitContract = class {};
 //#endregion
-export { ArkstackKitContract, ArkstackKitDriver };
-
-//# sourceMappingURL=index.js.map
+export { Arkstack, ArkstackKitContract, ArkstackKitDriver };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/contract",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "type": "module",
   "description": "Contract module for Arkstack, providing shared interfaces and type contracts used across the framework.",
   "homepage": "https://arkstack.toneflix.net",
@@ -27,6 +27,9 @@
     ".": "./dist/index.js",
     "./package.json": "./package.json"
   },
+  "dependencies": {
+    "@arkstack/foundry": "^0.5.3"
+  },
   "scripts": {
     "build": "tsdown --config-loader unrun",
     "version:patch": "pnpm version patch"

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["export type PromiseOrValue<T> = T | Promise<T>;\n\nexport interface ArkstackMiddlewareConfig<TMiddleware> {\n  global: TMiddleware[];\n  before: TMiddleware[];\n  after: TMiddleware[];\n}\n\nexport interface ArkstackRouteListOptions {\n  path?: string;\n}\n\nexport interface ArkstackRouterContract<TApp, TRoutes = unknown> {\n  bind (app: TApp): PromiseOrValue<unknown>;\n  list (options?: ArkstackRouteListOptions, app?: TApp): PromiseOrValue<TRoutes>;\n}\n\nexport interface ArkstackRouterAwareCore<TApp, TRoutes = unknown> {\n  getAppInstance (): TApp;\n  getRouter (): ArkstackRouterContract<TApp, TRoutes>;\n}\n\n/**\n * The ArkstackKitDriver class defines the contract for a driver \n * that can be used with the ArkstackKitContract. \n */\nexport abstract class ArkstackKitDriver<TApp, TMiddleware> {\n  abstract readonly name: string;\n  abstract createApp (): TApp;\n  abstract mountPublicAssets (app: TApp, publicPath: string): PromiseOrValue<void>;\n  abstract bindRouter (app: TApp): PromiseOrValue<void>;\n  abstract applyMiddleware (app: TApp, middleware: ArkstackMiddlewareConfig<TMiddleware>): PromiseOrValue<void>;\n  abstract applyMiddleware (app: TApp, middleware: TMiddleware): PromiseOrValue<void>;\n  registerErrorHandler (_app: TApp): PromiseOrValue<void> {\n    return\n  }\n  abstract start (app: TApp, port: number): PromiseOrValue<void>;\n}\n\n/**\n * The ArkstackKitContract class defines the contract for an \n * application that uses the ArkstackKitDriver.\n */\nexport abstract class ArkstackKitContract<TApp, TMiddleware> {\n  abstract app: TApp;\n  abstract driver: ArkstackKitDriver<TApp, TMiddleware>;\n  abstract middleware: ArkstackMiddlewareConfig<TMiddleware>;\n  abstract boot (port: number): Promise<void>;\n  abstract shutdown (): Promise<void>;\n}\n"],"mappings":";;;;;AA0BA,IAAsB,oBAAtB,MAA2D;CAOzD,qBAAsB,MAAkC;;;;;;AAU1D,IAAsB,sBAAtB,MAA6D"}