@rvoh/psychic 0.27.0 → 0.28.0

package/README.md

@@ -1,12 +1,14 @@
-> ATTENTION: we are currently in the process of releasing this code to the world, as of the afternoon of March 10th, 2025. This notice will be removed, and the version of this repo will be bumped to 1.0.0, once all of the repos have been migrated to the new spaces and we can verify that it is all working. This is anticipated to take 1 day.
+> ATTENTION: we are currently in the process of releasing this code to the world, as of the afternoon of March 10th, 2025. This notice will be removed, and the version of this repo will be bumped to 1.0.0, once all of the repos have been migrated to the new spaces and we can verify that it is all working. This is anticipated to be done in early April, 2025.
 
 # Psychic
 
-Psychic is a typescript first Node framework built on top of [kysely](http://kysely.dev) and heavily inspired by Ruby on Rails. It provides a light-weight routing layer around [expressjs](https://expressjs.com) to create a familiar MVC pattern for those coming from a conventional MVC framework, a type-safe ORM with an incredibly powerful autocomplete API, elegant redis and socket.io bindings for distributed websocket applications, the ability to couple with a front-end framework (like react, angular, etc...) and write specs that drive through your front end, while still maintaining a back end-centric context from which to write specs.
+Psychic is a typescript first Node framework built on top of [kysely](http://kysely.dev) and heavily inspired by Ruby on Rails. It provides a light-weight routing layer around [expressjs](https://expressjs.com) to create a familiar MVC pattern for those coming from a conventional MVC framework, and...
 
-For more comprehensive documentation, please see [The official Psychic guides](https://psychicframework.com). We will also be publishing api docs shortly, but the Psychic guides should be comprehensive enough to provide an understanding of the technology and how to use it.
+Introducing [dream](https://psychicframework.com/docs/models/overview)!, a robust, type-safe ORM with an incredibly powerful autocomplete API, through associations, polymorphism, single table inheritence, deep OpenAPI integration, and much more.
+
+In addition, psychic also provides elegant redis and socket.io bindings for distributed websocket applications, a powerful background job system integrated with bullmq to enable you to easily send any of your application code into redis for background processing, the ability to couple with a front-end framework (like nextjs, react, angular etc...) and write specs that drive through your front end, while still maintaining a back end-centric context from which to compose, and much more!
 
-NOTE: doing so will create the new app in the psychic folder, so once done testing remember to remove it.
+For more comprehensive documentation, please see [The official Psychic guides](https://psychicframework.com). We will also be publishing api docs shortly, but the Psychic guides should be comprehensive enough to provide an understanding of the technology and how to use it.
 
 ## Questions?
 

package/dist/cjs/src/bin/index.js

@@ -27,6 +27,20 @@ class PsychicBin {
         if (!bypassDreamSync)
             await dream_1.DreamBin.sync(() => { });
         await PsychicBin.syncTypes();
+        const psychicApp = index_js_1.default.getOrFail();
+        dream_1.DreamCLI.logger.logStartProgress('running post-sync operations...');
+        // call post-sync command in a separate process, so that newly-generated
+        // types can be reloaded and brought into all classes.
+        await dream_1.DreamCLI.spawn(psychicApp.psyCmd('post-sync'), {
+            onStdout: message => {
+                dream_1.DreamCLI.logger.logContinueProgress(`[post-sync]` + ' ' + message, {
+                    logPrefixColor: 'cyan',
+                });
+            },
+        });
+        dream_1.DreamCLI.logger.logEndProgress();
+    }
+    static async postSync() {
         const psychicApp = index_js_1.default.getOrFail();
         await PsychicBin.syncOpenapiJson();
         if (psychicApp.openapi?.syncEnumsToClient) {

package/dist/cjs/src/cli/index.js

@@ -50,6 +50,14 @@ class PsychicCLI {
             await index_js_1.default.sync();
             process.exit();
         });
+        program
+            .command('post-sync')
+            .description('an internal command that runs as the second stage of the `sync` command, since after types are rebuit, the application needs to be reloaded before autogenerating certain files, since those files will need to leverage the updated types')
+            .action(async () => {
+            await initializePsychicApplication();
+            await index_js_1.default.postSync();
+            process.exit();
+        });
         program
             .command('sync:routes')
             .description('reads the routes generated by your app and generates a cache file, which is then used to give autocomplete support to the route helper, amoongst other things.')

package/dist/cjs/src/error/psychic-application/init-missing-package-manager.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class PsychicApplicationInitMissingPackageManager extends Error {
+    constructor() {
+        super();
+    }
+    get message() {
+        return `
+must set packageManager when initializing a new PsychicApplication.
+
+within conf/app.ts, you must have a call to "#set('packageManager', '<YOUR_CHOSEN_PACKAGE_MANAGER>')", i.e.
+
+  // conf/app.ts
+  export default async (app: PsychicApplication) => {
+    await app.set('packageManager', 'yarn')
+  }
+    `;
+    }
+}
+exports.default = PsychicApplicationInitMissingPackageManager;

package/dist/cjs/src/helpers/path/psychicPath.js

@@ -12,6 +12,8 @@ function default_1(dreamPathType) {
             return psychicApp.paths.controllers;
         case 'controllerSpecs':
             return psychicApp.paths.controllerSpecs;
+        case 'services':
+            return psychicApp.paths.services;
         default:
             return (0, dream_1.dreamPath)(dreamPathType);
     }

package/dist/cjs/src/psychic-application/helpers/PsychicImporter.js

@@ -8,5 +8,14 @@ class PsychicImporter {
         const controllerClasses = (await Promise.all(controllerPaths.map(controllerPath => importCb(controllerPath).then(dreamClass => [controllerPath, dreamClass]))));
         return controllerClasses;
     }
+    static async importServices(pathToServices, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    importCb) {
+        const servicePaths = await dream_1.DreamImporter.ls(pathToServices);
+        const serviceClasses = (await Promise.all(servicePaths.map(servicePath => 
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        importCb(servicePath).then(serviceClass => [servicePath, serviceClass]))));
+        return serviceClasses;
+    }
 }
 exports.default = PsychicImporter;

package/dist/cjs/src/psychic-application/helpers/globalServiceKeyFromPath.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+function default_1(filepath, dirPath) {
+    const prefixPath = dirPath;
+    return ('services/' +
+        filepath
+            .replace(prefixPath, '')
+            .replace(/\.[jt]s$/, '')
+            .replace(/^\//, ''));
+}

package/dist/cjs/src/psychic-application/helpers/import/importServices.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = importServices;
+exports.setCachedServices = setCachedServices;
+exports.getServicesOrFail = getServicesOrFail;
+exports.getServicesOrBlank = getServicesOrBlank;
+const globalServiceKeyFromPath_js_1 = require("../globalServiceKeyFromPath.js");
+const PsychicImporter_js_1 = require("../PsychicImporter.js");
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _services;
+async function importServices(servicesPath, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+serviceImportCb) {
+    if (_services)
+        return _services;
+    _services = {};
+    const serviceClasses = await PsychicImporter_js_1.default.importServices(servicesPath, serviceImportCb);
+    for (const [servicePath, serviceClass] of serviceClasses) {
+        const typedServiceClass = serviceClass;
+        const serviceKey = (0, globalServiceKeyFromPath_js_1.default)(servicePath, servicesPath);
+        if (typeof typedServiceClass['setGlobalName'] === 'function') {
+            typedServiceClass['setGlobalName'](serviceKey);
+        }
+        else {
+            typedServiceClass.globalName = serviceKey;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        _services[serviceKey] = serviceClass;
+    }
+    return _services;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function setCachedServices(services) {
+    _services = services;
+}
+function getServicesOrFail() {
+    if (!_services)
+        throw new Error('Must call loadServices before calling getServicesOrFail');
+    return _services;
+}
+function getServicesOrBlank() {
+    return _services || {};
+}

package/dist/cjs/src/psychic-application/helpers/lookupClassByGlobalName.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = lookupClassByGlobalName;
 const dream_1 = require("@rvoh/dream");
 const importControllers_js_1 = require("./import/importControllers.js");
+const importServices_js_1 = require("./import/importServices.js");
 function lookupClassByGlobalName(name) {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     const lookup = (0, dream_1.lookupClassByGlobalName)(name);
@@ -11,6 +12,8 @@ function lookupClassByGlobalName(name) {
         return lookup;
     const combinedObj = {
         ...(0, importControllers_js_1.getControllersOrFail)(),
+        ...(0, importServices_js_1.getServicesOrFail)(),
     };
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
     return combinedObj[name] || null;
 }

package/dist/cjs/src/psychic-application/index.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PsychicApplicationAllowedPackageManagersEnumValues = void 0;
 const dream_1 = require("@rvoh/dream");
 const init_missing_api_root_js_1 = require("../error/psychic-application/init-missing-api-root.js");
 const init_missing_call_to_load_controllers_js_1 = require("../error/psychic-application/init-missing-call-to-load-controllers.js");
@@ -9,6 +10,9 @@ const EnvInternal_js_1 = require("../helpers/EnvInternal.js");
 const cache_js_1 = require("./cache.js");
 const importControllers_js_1 = require("./helpers/import/importControllers.js");
 const lookupClassByGlobalName_js_1 = require("./helpers/lookupClassByGlobalName.js");
+const init_missing_package_manager_js_1 = require("../error/psychic-application/init-missing-package-manager.js");
+const importServices_js_1 = require("./helpers/import/importServices.js");
+const pascalizeFileName_js_1 = require("../helpers/pascalizeFileName.js");
 class PsychicApplication {
     static async init(cb, dreamCb, opts = {}) {
         let psychicApp;
@@ -21,11 +25,27 @@ class PsychicApplication {
                 throw new init_missing_api_root_js_1.default();
             if (!psychicApp.routesCb)
                 throw new init_missing_routes_callback_js_1.default();
+            if (!exports.PsychicApplicationAllowedPackageManagersEnumValues.includes(psychicApp.packageManager))
+                throw new init_missing_package_manager_js_1.default();
             if (psychicApp.encryption?.cookies?.current)
                 this.checkKey('cookies', psychicApp.encryption.cookies.current.key, psychicApp.encryption.cookies.current.algorithm);
             await psychicApp.inflections?.();
             dreamApp.set('projectRoot', psychicApp.apiRoot);
             dreamApp.set('logger', psychicApp.logger);
+            dreamApp.on('repl:start', context => {
+                const psychicApp = PsychicApplication.getOrFail();
+                for (const globalName of Object.keys(psychicApp.services)) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                    if (!context[globalName]) {
+                        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+                        ;
+                        context[(0, pascalizeFileName_js_1.default)(globalName)] = psychicApp.services[globalName];
+                    }
+                }
+            });
+            for (const plugin of psychicApp.plugins) {
+                await plugin(psychicApp);
+            }
             (0, cache_js_1.cachePsychicApplication)(psychicApp);
         });
         return psychicApp;
@@ -34,6 +54,29 @@ class PsychicApplication {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-return
         return (0, lookupClassByGlobalName_js_1.default)(name);
     }
+    /**
+     * @internal
+     *
+     * used to provide the correct package manager syntax for running a script
+     * inside of the package.json "scripts" section.
+     */
+    packageManagerRunCmd(cmd) {
+        switch (this.packageManager) {
+            case 'npm':
+                return `npm run ${cmd}`;
+            default:
+                return `${this.packageManager} ${cmd}`;
+        }
+    }
+    /**
+     * @internal
+     *
+     * adds the necessary package manager prefix to the psy command provided
+     * i.e. `psyCmd('sync')`
+     */
+    psyCmd(cmd) {
+        return this.packageManagerRunCmd(`psy ${cmd}`);
+    }
     static checkKey(encryptionIdentifier, key, algorithm) {
         if (!dream_1.Encrypt.validateKey(key, algorithm))
             console.warn(`
@@ -108,14 +151,18 @@ Try setting it to something valid, like:
     get logger() {
         return this._logger;
     }
-    _sslCredentials;
+    _sslCredentials = undefined;
     get sslCredentials() {
         return this._sslCredentials;
     }
-    _saltRounds;
+    _saltRounds = undefined;
     get saltRounds() {
         return this._saltRounds;
     }
+    _packageManager;
+    get packageManager() {
+        return this._packageManager;
+    }
     _routesCb;
     get routesCb() {
         return this._routesCb;
@@ -143,6 +190,7 @@ Try setting it to something valid, like:
     _paths = {
         apiRoutes: 'src/conf/routes.ts',
         controllers: 'src/app/controllers',
+        services: 'src/app/services',
         controllerSpecs: 'spec/unit/controllers',
     };
     get paths() {
@@ -183,6 +231,10 @@ Try setting it to something valid, like:
     get loadedControllers() {
         return this._loadedControllers;
     }
+    _loadedServices = false;
+    get loadedServices() {
+        return this._loadedServices;
+    }
     _baseDefaultResponseHeaders = {
         ['cache-control']: 'max-age=0, private, must-revalidate',
     };
@@ -196,6 +248,13 @@ Try setting it to something valid, like:
     get controllers() {
         return (0, importControllers_js_1.getControllersOrFail)();
     }
+    get services() {
+        return (0, importServices_js_1.getServicesOrFail)();
+    }
+    _plugins = [];
+    get plugins() {
+        return this._plugins;
+    }
     async load(resourceType, resourcePath, 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     importCb) {
@@ -204,6 +263,10 @@ Try setting it to something valid, like:
                 await (0, importControllers_js_1.default)(this, resourcePath, importCb);
                 this._loadedControllers = true;
                 break;
+            case 'services':
+                await (0, importServices_js_1.default)(resourcePath, importCb);
+                this._loadedServices = true;
+                break;
         }
     }
     booted = false;
@@ -226,6 +289,9 @@ Try setting it to something valid, like:
         await this.inflections?.();
         this.booted = true;
     }
+    plugin(cb) {
+        this._plugins.push(cb);
+    }
     on(hookEventType, cb) {
         switch (hookEventType) {
             case 'server:error':
@@ -306,6 +372,9 @@ Try setting it to something valid, like:
             case 'port':
                 this._port = value;
                 break;
+            case 'packageManager':
+                this._packageManager = value;
+                break;
             case 'saltRounds':
                 this._saltRounds = value;
                 break;
@@ -344,3 +413,4 @@ Try setting it to something valid, like:
     }
 }
 exports.default = PsychicApplication;
+exports.PsychicApplicationAllowedPackageManagersEnumValues = ['yarn', 'npm', 'pnpm'];

package/dist/esm/src/bin/index.js

@@ -25,6 +25,20 @@ export default class PsychicBin {
         if (!bypassDreamSync)
             await DreamBin.sync(() => { });
         await PsychicBin.syncTypes();
+        const psychicApp = PsychicApplication.getOrFail();
+        DreamCLI.logger.logStartProgress('running post-sync operations...');
+        // call post-sync command in a separate process, so that newly-generated
+        // types can be reloaded and brought into all classes.
+        await DreamCLI.spawn(psychicApp.psyCmd('post-sync'), {
+            onStdout: message => {
+                DreamCLI.logger.logContinueProgress(`[post-sync]` + ' ' + message, {
+                    logPrefixColor: 'cyan',
+                });
+            },
+        });
+        DreamCLI.logger.logEndProgress();
+    }
+    static async postSync() {
         const psychicApp = PsychicApplication.getOrFail();
         await PsychicBin.syncOpenapiJson();
         if (psychicApp.openapi?.syncEnumsToClient) {

package/dist/esm/src/cli/index.js

@@ -48,6 +48,14 @@ export default class PsychicCLI {
             await PsychicBin.sync();
             process.exit();
         });
+        program
+            .command('post-sync')
+            .description('an internal command that runs as the second stage of the `sync` command, since after types are rebuit, the application needs to be reloaded before autogenerating certain files, since those files will need to leverage the updated types')
+            .action(async () => {
+            await initializePsychicApplication();
+            await PsychicBin.postSync();
+            process.exit();
+        });
         program
             .command('sync:routes')
             .description('reads the routes generated by your app and generates a cache file, which is then used to give autocomplete support to the route helper, amoongst other things.')

package/dist/esm/src/error/psychic-application/init-missing-package-manager.js

@@ -0,0 +1,17 @@
+export default class PsychicApplicationInitMissingPackageManager extends Error {
+    constructor() {
+        super();
+    }
+    get message() {
+        return `
+must set packageManager when initializing a new PsychicApplication.
+
+within conf/app.ts, you must have a call to "#set('packageManager', '<YOUR_CHOSEN_PACKAGE_MANAGER>')", i.e.
+
+  // conf/app.ts
+  export default async (app: PsychicApplication) => {
+    await app.set('packageManager', 'yarn')
+  }
+    `;
+    }
+}

package/dist/esm/src/helpers/path/psychicPath.js

@@ -9,6 +9,8 @@ export default function (dreamPathType) {
             return psychicApp.paths.controllers;
         case 'controllerSpecs':
             return psychicApp.paths.controllerSpecs;
+        case 'services':
+            return psychicApp.paths.services;
         default:
             return dreamPath(dreamPathType);
     }

package/dist/esm/src/psychic-application/helpers/PsychicImporter.js

@@ -6,4 +6,13 @@ export default class PsychicImporter {
         const controllerClasses = (await Promise.all(controllerPaths.map(controllerPath => importCb(controllerPath).then(dreamClass => [controllerPath, dreamClass]))));
         return controllerClasses;
     }
+    static async importServices(pathToServices, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    importCb) {
+        const servicePaths = await DreamImporter.ls(pathToServices);
+        const serviceClasses = (await Promise.all(servicePaths.map(servicePath => 
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        importCb(servicePath).then(serviceClass => [servicePath, serviceClass]))));
+        return serviceClasses;
+    }
 }

package/dist/esm/src/psychic-application/helpers/globalServiceKeyFromPath.js

@@ -0,0 +1,8 @@
+export default function (filepath, dirPath) {
+    const prefixPath = dirPath;
+    return ('services/' +
+        filepath
+            .replace(prefixPath, '')
+            .replace(/\.[jt]s$/, '')
+            .replace(/^\//, ''));
+}

package/dist/esm/src/psychic-application/helpers/import/importServices.js

@@ -0,0 +1,37 @@
+import globalServiceKeyFromPath from '../globalServiceKeyFromPath.js';
+import PsychicImporter from '../PsychicImporter.js';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _services;
+export default async function importServices(servicesPath, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+serviceImportCb) {
+    if (_services)
+        return _services;
+    _services = {};
+    const serviceClasses = await PsychicImporter.importServices(servicesPath, serviceImportCb);
+    for (const [servicePath, serviceClass] of serviceClasses) {
+        const typedServiceClass = serviceClass;
+        const serviceKey = globalServiceKeyFromPath(servicePath, servicesPath);
+        if (typeof typedServiceClass['setGlobalName'] === 'function') {
+            typedServiceClass['setGlobalName'](serviceKey);
+        }
+        else {
+            typedServiceClass.globalName = serviceKey;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        _services[serviceKey] = serviceClass;
+    }
+    return _services;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function setCachedServices(services) {
+    _services = services;
+}
+export function getServicesOrFail() {
+    if (!_services)
+        throw new Error('Must call loadServices before calling getServicesOrFail');
+    return _services;
+}
+export function getServicesOrBlank() {
+    return _services || {};
+}

package/dist/esm/src/psychic-application/helpers/lookupClassByGlobalName.js

@@ -1,5 +1,6 @@
 import { lookupClassByGlobalName as dreamLookupClassByGlobalName } from '@rvoh/dream';
 import { getControllersOrFail } from './import/importControllers.js';
+import { getServicesOrFail } from './import/importServices.js';
 export default function lookupClassByGlobalName(name) {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     const lookup = dreamLookupClassByGlobalName(name);
@@ -8,6 +9,8 @@ export default function lookupClassByGlobalName(name) {
         return lookup;
     const combinedObj = {
         ...getControllersOrFail(),
+        ...getServicesOrFail(),
     };
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
     return combinedObj[name] || null;
 }

package/dist/esm/src/psychic-application/index.js

@@ -7,6 +7,9 @@ import EnvInternal from '../helpers/EnvInternal.js';
 import { cachePsychicApplication, getCachedPsychicApplicationOrFail } from './cache.js';
 import importControllers, { getControllersOrFail } from './helpers/import/importControllers.js';
 import lookupClassByGlobalName from './helpers/lookupClassByGlobalName.js';
+import PsychicApplicationInitMissingPackageManager from '../error/psychic-application/init-missing-package-manager.js';
+import importServices, { getServicesOrFail } from './helpers/import/importServices.js';
+import pascalizeFileName from '../helpers/pascalizeFileName.js';
 export default class PsychicApplication {
     static async init(cb, dreamCb, opts = {}) {
         let psychicApp;
@@ -19,11 +22,27 @@ export default class PsychicApplication {
                 throw new PsychicApplicationInitMissingApiRoot();
             if (!psychicApp.routesCb)
                 throw new PsychicApplicationInitMissingRoutesCallback();
+            if (!PsychicApplicationAllowedPackageManagersEnumValues.includes(psychicApp.packageManager))
+                throw new PsychicApplicationInitMissingPackageManager();
             if (psychicApp.encryption?.cookies?.current)
                 this.checkKey('cookies', psychicApp.encryption.cookies.current.key, psychicApp.encryption.cookies.current.algorithm);
             await psychicApp.inflections?.();
             dreamApp.set('projectRoot', psychicApp.apiRoot);
             dreamApp.set('logger', psychicApp.logger);
+            dreamApp.on('repl:start', context => {
+                const psychicApp = PsychicApplication.getOrFail();
+                for (const globalName of Object.keys(psychicApp.services)) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                    if (!context[globalName]) {
+                        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+                        ;
+                        context[pascalizeFileName(globalName)] = psychicApp.services[globalName];
+                    }
+                }
+            });
+            for (const plugin of psychicApp.plugins) {
+                await plugin(psychicApp);
+            }
             cachePsychicApplication(psychicApp);
         });
         return psychicApp;
@@ -32,6 +51,29 @@ export default class PsychicApplication {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-return
         return lookupClassByGlobalName(name);
     }
+    /**
+     * @internal
+     *
+     * used to provide the correct package manager syntax for running a script
+     * inside of the package.json "scripts" section.
+     */
+    packageManagerRunCmd(cmd) {
+        switch (this.packageManager) {
+            case 'npm':
+                return `npm run ${cmd}`;
+            default:
+                return `${this.packageManager} ${cmd}`;
+        }
+    }
+    /**
+     * @internal
+     *
+     * adds the necessary package manager prefix to the psy command provided
+     * i.e. `psyCmd('sync')`
+     */
+    psyCmd(cmd) {
+        return this.packageManagerRunCmd(`psy ${cmd}`);
+    }
     static checkKey(encryptionIdentifier, key, algorithm) {
         if (!Encrypt.validateKey(key, algorithm))
             console.warn(`
@@ -106,14 +148,18 @@ Try setting it to something valid, like:
     get logger() {
         return this._logger;
     }
-    _sslCredentials;
+    _sslCredentials = undefined;
     get sslCredentials() {
         return this._sslCredentials;
     }
-    _saltRounds;
+    _saltRounds = undefined;
     get saltRounds() {
         return this._saltRounds;
     }
+    _packageManager;
+    get packageManager() {
+        return this._packageManager;
+    }
     _routesCb;
     get routesCb() {
         return this._routesCb;
@@ -141,6 +187,7 @@ Try setting it to something valid, like:
     _paths = {
         apiRoutes: 'src/conf/routes.ts',
         controllers: 'src/app/controllers',
+        services: 'src/app/services',
         controllerSpecs: 'spec/unit/controllers',
     };
     get paths() {
@@ -181,6 +228,10 @@ Try setting it to something valid, like:
     get loadedControllers() {
         return this._loadedControllers;
     }
+    _loadedServices = false;
+    get loadedServices() {
+        return this._loadedServices;
+    }
     _baseDefaultResponseHeaders = {
         ['cache-control']: 'max-age=0, private, must-revalidate',
     };
@@ -194,6 +245,13 @@ Try setting it to something valid, like:
     get controllers() {
         return getControllersOrFail();
     }
+    get services() {
+        return getServicesOrFail();
+    }
+    _plugins = [];
+    get plugins() {
+        return this._plugins;
+    }
     async load(resourceType, resourcePath, 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     importCb) {
@@ -202,6 +260,10 @@ Try setting it to something valid, like:
                 await importControllers(this, resourcePath, importCb);
                 this._loadedControllers = true;
                 break;
+            case 'services':
+                await importServices(resourcePath, importCb);
+                this._loadedServices = true;
+                break;
         }
     }
     booted = false;
@@ -224,6 +286,9 @@ Try setting it to something valid, like:
         await this.inflections?.();
         this.booted = true;
     }
+    plugin(cb) {
+        this._plugins.push(cb);
+    }
     on(hookEventType, cb) {
         switch (hookEventType) {
             case 'server:error':
@@ -304,6 +369,9 @@ Try setting it to something valid, like:
             case 'port':
                 this._port = value;
                 break;
+            case 'packageManager':
+                this._packageManager = value;
+                break;
             case 'saltRounds':
                 this._saltRounds = value;
                 break;
@@ -341,3 +409,4 @@ Try setting it to something valid, like:
         }
     }
 }
+export const PsychicApplicationAllowedPackageManagersEnumValues = ['yarn', 'npm', 'pnpm'];

package/dist/types/src/bin/index.d.ts

@@ -5,6 +5,7 @@ export default class PsychicBin {
     static sync({ bypassDreamSync }?: {
         bypassDreamSync?: boolean;
     }): Promise<void>;
+    static postSync(): Promise<void>;
     static syncTypes(customTypes?: any): Promise<void>;
     static syncOpenapiJson(): Promise<void>;
     static syncRoutes(): Promise<void>;

package/dist/types/src/error/psychic-application/init-missing-package-manager.d.ts

@@ -0,0 +1,4 @@
+export default class PsychicApplicationInitMissingPackageManager extends Error {
+    constructor();
+    get message(): string;
+}

package/dist/types/src/helpers/path/psychicPath.d.ts

@@ -1,4 +1,4 @@
 export default function (dreamPathType: PsychicPaths): string;
 type DreamPaths = 'models' | 'modelSpecs' | 'serializers' | 'db' | 'conf' | 'factories';
-export type PsychicPaths = DreamPaths | 'apiRoutes' | 'controllers' | 'controllerSpecs';
+export type PsychicPaths = DreamPaths | 'apiRoutes' | 'controllers' | 'controllerSpecs' | 'services';
 export {};

package/dist/types/src/psychic-application/helpers/PsychicImporter.d.ts

@@ -1,4 +1,5 @@
 import PsychicController from '../../controller/index.js';
 export default class PsychicImporter {
     static importControllers(controllersPath: string, importCb: (path: string) => Promise<any>): Promise<[string, typeof PsychicController][]>;
+    static importServices(pathToServices: string, importCb: (path: string) => Promise<any>): Promise<[string, any][]>;
 }

package/dist/types/src/psychic-application/helpers/globalServiceKeyFromPath.d.ts

@@ -0,0 +1 @@
+export default function (filepath: string, dirPath: string): string;

package/dist/types/src/psychic-application/helpers/import/importServices.d.ts

@@ -0,0 +1,4 @@
+export default function importServices(servicesPath: string, serviceImportCb: (path: string) => Promise<any>): Promise<Record<string, any>>;
+export declare function setCachedServices(services: Record<string, any>): void;
+export declare function getServicesOrFail(): Record<string, any>;
+export declare function getServicesOrBlank(): Record<string, any>;

package/dist/types/src/psychic-application/index.d.ts

@@ -11,6 +11,20 @@ import { PsychicHookEventType, PsychicHookLoadEventTypes } from './types.js';
 export default class PsychicApplication {
     static init(cb: (app: PsychicApplication) => void | Promise<void>, dreamCb: (app: DreamApplication) => void | Promise<void>, opts?: PsychicApplicationInitOptions): Promise<PsychicApplication>;
     static lookupClassByGlobalName(name: string): any;
+    /**
+     * @internal
+     *
+     * used to provide the correct package manager syntax for running a script
+     * inside of the package.json "scripts" section.
+     */
+    packageManagerRunCmd(cmd: string): string;
+    /**
+     * @internal
+     *
+     * adds the necessary package manager prefix to the psy command provided
+     * i.e. `psyCmd('sync')`
+     */
+    psyCmd(cmd: string): string;
     private static checkKey;
     /**
      * Returns the cached psychic application if it has been set.
@@ -45,10 +59,12 @@ export default class PsychicApplication {
     };
     private _logger;
     get logger(): DreamLogger;
-    private _sslCredentials?;
+    private _sslCredentials;
     get sslCredentials(): PsychicSslCredentials | undefined;
-    private _saltRounds?;
+    private _saltRounds;
     get saltRounds(): number | undefined;
+    private _packageManager;
+    get packageManager(): "yarn" | "npm" | "pnpm";
     private _routesCb;
     get routesCb(): (r: PsychicRouter) => void | Promise<void>;
     private _openapi;
@@ -67,22 +83,30 @@ export default class PsychicApplication {
     private get overrides();
     private _loadedControllers;
     get loadedControllers(): boolean;
+    private _loadedServices;
+    get loadedServices(): boolean;
     private _baseDefaultResponseHeaders;
     private _defaultResponseHeaders;
     get defaultResponseHeaders(): {
         [x: string]: string | null;
     };
     get controllers(): Record<string, typeof import("../index.js").PsychicController>;
-    load<RT extends 'controllers'>(resourceType: RT, resourcePath: string, importCb: (path: string) => Promise<any>): Promise<void>;
+    get services(): Record<string, any>;
+    private _plugins;
+    get plugins(): ((app: PsychicApplication) => void | Promise<void>)[];
+    load<RT extends 'controllers' | 'services'>(resourceType: RT, resourcePath: string, importCb: (path: string) => Promise<any>): Promise<void>;
     private booted;
     boot(force?: boolean): Promise<void>;
+    plugin(cb: (app: PsychicApplication) => void | Promise<void>): void;
     on<T extends PsychicHookEventType>(hookEventType: T, cb: T extends 'server:error' ? (err: Error, req: Request, res: Response) => void | Promise<void> : T extends 'server:init' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:start' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:shutdown' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:init:after-routes' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'sync' ? () => any : (conf: PsychicApplication) => void | Promise<void>): void;
     set(option: 'openapi', name: string, value: NamedPsychicOpenapiOptions): void;
-    set<Opt extends PsychicApplicationOption>(option: Opt, value: Opt extends 'appName' ? string : Opt extends 'apiOnly' ? boolean : Opt extends 'defaultResponseHeaders' ? Record<string, string | null> : Opt extends 'encryption' ? PsychicApplicationEncryptionOptions : Opt extends 'cors' ? CorsOptions : Opt extends 'cookie' ? CustomCookieOptions : Opt extends 'apiRoot' ? string : Opt extends 'sessionCookieName' ? string : Opt extends 'clientRoot' ? string : Opt extends 'json' ? bodyParser.Options : Opt extends 'logger' ? PsychicLogger : Opt extends 'client' ? PsychicClientOptions : Opt extends 'ssl' ? PsychicSslCredentials : Opt extends 'openapi' ? DefaultPsychicOpenapiOptions : Opt extends 'paths' ? PsychicPathOptions : Opt extends 'port' ? number : Opt extends 'saltRounds' ? number : Opt extends 'inflections' ? () => void | Promise<void> : Opt extends 'routes' ? (r: PsychicRouter) => void | Promise<void> : never): void;
+    set<Opt extends PsychicApplicationOption>(option: Opt, value: Opt extends 'appName' ? string : Opt extends 'apiOnly' ? boolean : Opt extends 'defaultResponseHeaders' ? Record<string, string | null> : Opt extends 'encryption' ? PsychicApplicationEncryptionOptions : Opt extends 'cors' ? CorsOptions : Opt extends 'cookie' ? CustomCookieOptions : Opt extends 'apiRoot' ? string : Opt extends 'sessionCookieName' ? string : Opt extends 'clientRoot' ? string : Opt extends 'json' ? bodyParser.Options : Opt extends 'logger' ? PsychicLogger : Opt extends 'client' ? PsychicClientOptions : Opt extends 'ssl' ? PsychicSslCredentials : Opt extends 'openapi' ? DefaultPsychicOpenapiOptions : Opt extends 'paths' ? PsychicPathOptions : Opt extends 'port' ? number : Opt extends 'saltRounds' ? number : Opt extends 'packageManager' ? PsychicApplicationAllowedPackageManagersEnum : Opt extends 'inflections' ? () => void | Promise<void> : Opt extends 'routes' ? (r: PsychicRouter) => void | Promise<void> : never): void;
     override<Override extends keyof PsychicApplicationOverrides>(override: Override, value: PsychicApplicationOverrides[Override]): void;
     private runHooksFor;
 }
-export type PsychicApplicationOption = 'appName' | 'apiOnly' | 'apiRoot' | 'encryption' | 'sessionCookieName' | 'client' | 'clientRoot' | 'cookie' | 'cors' | 'defaultResponseHeaders' | 'inflections' | 'json' | 'logger' | 'openapi' | 'paths' | 'port' | 'routes' | 'saltRounds' | 'ssl';
+export type PsychicApplicationOption = 'appName' | 'apiOnly' | 'apiRoot' | 'encryption' | 'sessionCookieName' | 'client' | 'clientRoot' | 'cookie' | 'cors' | 'defaultResponseHeaders' | 'inflections' | 'json' | 'logger' | 'openapi' | 'packageManager' | 'paths' | 'port' | 'routes' | 'saltRounds' | 'ssl';
+export declare const PsychicApplicationAllowedPackageManagersEnumValues: readonly ["yarn", "npm", "pnpm"];
+export type PsychicApplicationAllowedPackageManagersEnum = (typeof PsychicApplicationAllowedPackageManagersEnumValues)[number];
 export interface PsychicApplicationSpecialHooks {
     sync: (() => any)[];
     serverInit: ((server: PsychicServer) => void | Promise<void>)[];
@@ -143,6 +167,7 @@ interface PsychicOpenapiInfo {
 }
 interface PsychicPathOptions {
     apiRoutes?: string;
+    services?: string;
     controllers?: string;
     controllerSpecs?: string;
 }

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "author": "RVOHealth",
   "repository": {
     "type": "git",
@@ -24,11 +24,10 @@
   ],
   "scripts": {
     "client": "yarn --cwd=./client start",
-    "psy": "NODE_ENV=${NODE_ENV:-test} yarn psyts",
+    "psy": "PSYCHIC_CORE_DEVELOPMENT=1 NODE_ENV=${NODE_ENV:-test} yarn psyts",
     "psyjs": "node ./dist/test-app/src/cli/index.js",
     "psyts": "NODE_ENV=${NODE_ENV:-test} tsx ./test-app/src/cli/index.ts",
-    "psycore": "PSYCHIC_CORE_DEVELOPMENT=1 yarn psyts",
-    "gpsycore": "PSYCHIC_CORE_DEVELOPMENT=1 tsx ./global-cli/main.ts",
+    "gpsy": "PSYCHIC_CORE_DEVELOPMENT=1 tsx ./global-cli/main.ts",
     "build": "echo \"building cjs...\" && rm -rf dist && npx tsc -p ./tsconfig.cjs.build.json && echo \"building esm...\" && npx tsc -p ./tsconfig.esm.build.json",
     "build:test-app": "rm -rf dist && echo \"building test app to esm...\" && npx tsc -p ./tsconfig.esm.build.test-app.json && echo \"building test app to cjs...\" && npx tsc -p ./tsconfig.cjs.build.test-app.json",
     "dev": "PSYCHIC_CORE_DEVELOPMENT=1 NODE_ENV=development tsx ./test-app/main.ts",
@@ -63,7 +62,7 @@
   "devDependencies": {
     "@eslint/js": "^9.19.0",
     "@jest-mock/express": "^3.0.0",
-    "@rvoh/dream": "^0.31.3",
+    "@rvoh/dream": "^0.33.0",
     "@rvoh/dream-spec-helpers": "=0.1.0",
     "@rvoh/psychic-spec-helpers": "=0.2.0",
     "@types/express": "^4.17.21",
@@ -89,8 +88,8 @@
     "typedoc": "^0.26.6",
     "typescript": "^5.5.4",
     "typescript-eslint": "=7.18.0",
-    "vitest": "^3.0.9",
+    "vitest": "^3.1.1",
     "winston": "^3.14.2"
   },
   "packageManager": "yarn@4.7.0"
-}
+}

package/dist/cjs/src/helpers/sspawn.js

@@ -1,26 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = sspawn;
-exports.ssspawn = ssspawn;
-const child_process_1 = require("child_process");
-function sspawn(command, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-opts = {}) {
-    return new Promise((accept, reject) => {
-        ssspawn(command, opts).on('close', code => {
-            if (code !== 0)
-                reject(new Error(code?.toString()));
-            accept({});
-        });
-    });
-}
-function ssspawn(command, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-opts = {}) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-    return (0, child_process_1.spawn)(command, {
-        stdio: 'inherit',
-        shell: true,
-        ...opts,
-    });
-}

package/dist/esm/src/helpers/sspawn.js

@@ -1,22 +0,0 @@
-import { spawn } from 'child_process';
-export default function sspawn(command, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-opts = {}) {
-    return new Promise((accept, reject) => {
-        ssspawn(command, opts).on('close', code => {
-            if (code !== 0)
-                reject(new Error(code?.toString()));
-            accept({});
-        });
-    });
-}
-export function ssspawn(command, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-opts = {}) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-    return spawn(command, {
-        stdio: 'inherit',
-        shell: true,
-        ...opts,
-    });
-}

package/dist/types/src/helpers/sspawn.d.ts

@@ -1,2 +0,0 @@
-export default function sspawn(command: string, opts?: any): Promise<unknown>;
-export declare function ssspawn(command: string, opts?: any): import("child_process").ChildProcessWithoutNullStreams;