@rvoh/psychic 0.24.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RVO Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+> 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.
+
+# 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.
+
+For more comprehensive documentation, please see [The official Psychic guides](https://psychic-docs.netlify.app). 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.
+
+NOTE: doing so will create the new app in the psychic folder, so once done testing remember to remove it.
+
+## Questions?
+
+- **Ask them on [Stack Overflow](https://stackoverflow.com)**, using the `[psychic]` tag.
+
+## Contributing
+
+Psychic is an open source library, so we encourage you to actively contribute. Visit our [Contributing](https://github.com/rvohealth/psychic/CONTRIBUTING.md) guide to learn more about the processes we use for submitting pull requests or issues.
+
+Are you trying to report a possible security vulnerability? Visit our [Security Policy](https://github.com/rvohealth/psychic/SECURITY.md) for guidelines about how to proceed.

package/dist/cjs/src/bin/helpers/enumsAndTheirValues.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = enumsAndTheirValues;
+const dream_1 = require("@rvoh/dream");
+const kysely_1 = require("kysely");
+async function enumsAndTheirValues() {
+    const { rows } = await (0, kysely_1.sql) `
+SELECT pg_type.typname AS enum_type, pg_enum.enumlabel AS enum_label FROM pg_type JOIN pg_enum ON pg_enum.enumtypid = pg_type.oid;
+
+`.execute((0, dream_1.db)('primary'));
+    const rowData = {};
+    rows.forEach(row => {
+        rowData[row.enumType] ||= [];
+        rowData[row.enumType].push(row.enumLabel);
+    });
+    return rowData;
+}

package/dist/cjs/src/bin/helpers/enumsFileStr.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = enumsFileStr;
+const autogeneratedFileDisclaimer_js_1 = require("../../helpers/autogeneratedFileDisclaimer.js");
+const pascalizeFileName_js_1 = require("../../helpers/pascalizeFileName.js");
+const enumsAndTheirValues_js_1 = require("./enumsAndTheirValues.js");
+async function enumsFileStr() {
+    const enums = await (0, enumsAndTheirValues_js_1.default)();
+    let enumsFileStr = (0, autogeneratedFileDisclaimer_js_1.default)();
+    Object.keys(enums).forEach(enumName => {
+        const exportedTypeName = (0, pascalizeFileName_js_1.default)(enumName) + 'Values';
+        const values = enums[enumName];
+        enumsFileStr += `\
+export const ${exportedTypeName} = [
+  ${values.map(val => `'${val}'`).join(',\n  ')}
+] as const
+
+`;
+    });
+    return enumsFileStr;
+}

package/dist/cjs/src/bin/helpers/generateRouteTypes.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = generateRouteTypes;
+const dream_1 = require("@rvoh/dream");
+const fs = require("fs/promises");
+const path = require("path");
+const index_js_1 = require("../../psychic-application/index.js");
+async function generateRouteTypes(routes) {
+    const fileStr = `\
+  export type RouteTypes =
+  ${(0, dream_1.uniq)(routes.map(routeConf => `  | '/${routeConf.path.replace(/^\//, '')}'`)).join('\n')}
+  `;
+    const psychicApp = index_js_1.default.getOrFail();
+    const routeTypesPath = path.join(psychicApp.apiRoot, 'src/conf/routeTypes.ts');
+    await fs.writeFile(routeTypesPath, fileStr);
+}

package/dist/cjs/src/bin/helpers/printRoutes.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = printRoutes;
+const colors = require("colorette");
+const index_js_1 = require("../../server/index.js");
+async function printRoutes() {
+    const server = new index_js_1.default();
+    await server.boot();
+    const routes = await server.routes();
+    const expressions = buildExpressions(routes);
+    // NOTE: intentionally doing this outside of the expression loop below
+    // to avoid N+1
+    const desiredFirstGapSpaceCount = calculateNumSpacesInFirstGap(expressions);
+    const desiredLastGapSpaceCount = calculateNumSpacesInLastGap(expressions);
+    expressions.forEach(([beginning, end], i) => {
+        const partialExpression = `${beginning}${makeSpaces(beginning, desiredFirstGapSpaceCount)}${end}`;
+        const closingSpaces = makeSpaces(partialExpression, desiredLastGapSpaceCount);
+        const expression = `${partialExpression}${closingSpaces}`;
+        const colorizedExpression = i % 2 ? colors.bgWhite(colors.black(expression)) : expression;
+        console.log(colorizedExpression);
+    });
+}
+function buildExpressions(routes) {
+    return routes.map(route => {
+        const method = route.httpMethod.toUpperCase();
+        const numMethodSpaces = 8 - method.length;
+        const beginningOfExpression = `${route.httpMethod.toUpperCase()}${' '.repeat(numMethodSpaces)}${route.path}`;
+        const endOfExpression = route.controller.disaplayName + '#' + route.action;
+        return [beginningOfExpression, endOfExpression];
+    });
+}
+function makeSpaces(expression, desiredCount) {
+    return ' '.repeat(Math.max(desiredCount - expression.length, 1));
+}
+function calculateNumSpacesInFirstGap(expressions) {
+    let desiredSpaceCount = 0;
+    expressions.forEach(expression => {
+        if (expression[0].length > desiredSpaceCount)
+            desiredSpaceCount = expression[0].length;
+    });
+    const gapSpaces = 3;
+    return desiredSpaceCount + gapSpaces;
+}
+function calculateNumSpacesInLastGap(expressions) {
+    const desiredFirstGapSpaceCount = calculateNumSpacesInFirstGap(expressions);
+    let desiredSpaceCount = 0;
+    expressions.forEach(([beginning, end]) => {
+        const spaces = desiredFirstGapSpaceCount - beginning.length;
+        const expression = `${beginning}${spaces}${end}`;
+        if (expression.length > desiredSpaceCount)
+            desiredSpaceCount = expression.length;
+    });
+    return desiredSpaceCount + 3;
+}

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

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const dream_1 = require("@rvoh/dream");
+const fs = require("fs/promises");
+const path = require("path");
+const TypesBuilder_js_1 = require("../cli/helpers/TypesBuilder.js");
+const controller_js_1 = require("../generate/controller.js");
+const resource_js_1 = require("../generate/resource.js");
+const typechecks_js_1 = require("../helpers/typechecks.js");
+const app_js_1 = require("../openapi-renderer/app.js");
+const index_js_1 = require("../psychic-application/index.js");
+const index_js_2 = require("../server/index.js");
+const enumsFileStr_js_1 = require("./helpers/enumsFileStr.js");
+const generateRouteTypes_js_1 = require("./helpers/generateRouteTypes.js");
+const printRoutes_js_1 = require("./helpers/printRoutes.js");
+class PsychicBin {
+    static async generateController(controllerName, actions) {
+        await (0, controller_js_1.default)({ fullyQualifiedControllerName: controllerName, actions });
+    }
+    static async generateResource(route, fullyQualifiedModelName, columnsWithTypes) {
+        await (0, resource_js_1.default)({ route, fullyQualifiedModelName, columnsWithTypes });
+    }
+    static async routes() {
+        await (0, printRoutes_js_1.default)();
+    }
+    static async sync({ bypassDreamSync = false } = {}) {
+        if (!bypassDreamSync)
+            await dream_1.DreamBin.sync(() => { });
+        await PsychicBin.syncTypes();
+        const psychicApp = index_js_1.default.getOrFail();
+        if (!psychicApp.apiOnly) {
+            await PsychicBin.syncOpenapiJson();
+        }
+        if (psychicApp.openapi?.syncEnumsToClient) {
+            await this.syncClientEnums();
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let output = {};
+        for (const hook of psychicApp.specialHooks.sync) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            const res = await hook();
+            if ((0, typechecks_js_1.isObject)(res)) {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                output = { ...output, ...res };
+            }
+        }
+        if (Object.keys(output).length) {
+            await PsychicBin.syncTypes(output);
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static async syncTypes(customTypes = undefined) {
+        console.log(`syncing types/psychic.ts...`);
+        await TypesBuilder_js_1.default.sync(customTypes);
+        console.log(`done syncing types/psychic.ts!`);
+    }
+    static async syncOpenapiJson() {
+        console.log(`syncing openapi...`);
+        await app_js_1.default.sync();
+        console.log(`done syncing openapi!`);
+    }
+    static async syncRoutes() {
+        console.log('syncing routes...');
+        const server = new index_js_2.default();
+        await server.boot();
+        const routes = await server.routes();
+        await (0, generateRouteTypes_js_1.default)(routes);
+        console.log('done syncing routes!');
+    }
+    static async syncClientEnums() {
+        console.log('syncing client enums...');
+        const psychicApp = index_js_1.default.getOrFail();
+        const apiPath = path.join(psychicApp.clientRoot, psychicApp.client.apiPath);
+        const enumsStr = await (0, enumsFileStr_js_1.default)();
+        await fs.writeFile(`${apiPath}/enums.ts`, enumsStr);
+        console.log('done syncing client enums!');
+    }
+}
+exports.default = PsychicBin;

package/dist/cjs/src/cli/helpers/TypesBuilder.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const dream_1 = require("@rvoh/dream");
+const fs = require("fs/promises");
+const path = require("path");
+const index_js_1 = require("../../psychic-application/index.js");
+class TypesBuilder {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static async sync(customTypes = undefined) {
+        const dreamApp = dream_1.DreamApplication.getOrFail();
+        const schemaPath = path.join(dreamApp.projectRoot, dreamApp.paths.types, 'psychic.ts');
+        await fs.writeFile(schemaPath, this.build(customTypes));
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static build(customTypes = undefined) {
+        const psychicApp = index_js_1.default.getOrFail();
+        const output = {
+            openapiNames: Object.keys(psychicApp.openapi),
+            ...(customTypes || {}),
+        };
+        return `const psychicTypes = ${JSON.stringify(output, null, 2)} as const
+
+export default psychicTypes`;
+    }
+}
+exports.default = TypesBuilder;

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

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const dream_1 = require("@rvoh/dream");
+const index_js_1 = require("../bin/index.js");
+const EnvInternal_js_1 = require("../helpers/EnvInternal.js");
+class PsychicCLI {
+    static provide(program, { initializePsychicApplication, seedDb, }) {
+        dream_1.DreamCLI.generateDreamCli(program, {
+            initializeDreamApplication: initializePsychicApplication,
+            seedDb,
+            onSync: async () => {
+                await index_js_1.default.sync({ bypassDreamSync: true });
+            },
+        });
+        program
+            .command('generate:resource')
+            .alias('g:resource')
+            .description('create a Dream model, migration, controller, serializer, and spec placeholders')
+            .argument('<path>', 'URL path from root domain')
+            .argument('<modelName>', 'the name of the model to create, e.g. Post or Settings/CommunicationPreferences')
+            .argument('[columnsWithTypes...]', 'properties of the model property1:text/string/enum/etc. property2:text/string/enum/etc. ... propertyN:text/string/enum/etc.')
+            .action(async (route, modelName, columnsWithTypes) => {
+            EnvInternal_js_1.default.provideDefaultNodeEnv('test');
+            await initializePsychicApplication();
+            await index_js_1.default.generateResource(route, modelName, columnsWithTypes);
+            process.exit();
+        });
+        program
+            .command('generate:controller')
+            .alias('g:controller')
+            .description('create a controller')
+            .argument('<controllerName>', 'the name of the controller to create, including namespaces, e.g. Posts or Api/V1/Posts')
+            .argument('[actions...]', 'the names of controller actions to create')
+            .action(async (controllerName, actions) => {
+            EnvInternal_js_1.default.provideDefaultNodeEnv('test');
+            await initializePsychicApplication();
+            await index_js_1.default.generateController(controllerName, actions);
+            process.exit();
+        });
+        program
+            .command('routes')
+            .description('examines your current models, building a type-map of the associations so that the ORM can understand your relational setup. This is commited to your repo, and synced to the dream repo for consumption within the underlying library.')
+            .action(async () => {
+            EnvInternal_js_1.default.provideDefaultNodeEnv('test');
+            await initializePsychicApplication();
+            await index_js_1.default.routes();
+            process.exit();
+        });
+        program
+            .command('sync')
+            .description('sync introspects your database, updating your schema to reflect, and then syncs the new schema with the installed dream node module, allowing it provide your schema to the underlying kysely integration')
+            .action(async () => {
+            EnvInternal_js_1.default.provideDefaultNodeEnv('test');
+            await initializePsychicApplication();
+            await index_js_1.default.sync();
+            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.')
+            .action(async () => {
+            EnvInternal_js_1.default.provideDefaultNodeEnv('test');
+            await index_js_1.default.syncRoutes();
+        });
+        program
+            .command('sync:openapi')
+            .description('syncs openapi.json file to current state of all psychic controllers within the app')
+            .action(async () => {
+            EnvInternal_js_1.default.provideDefaultNodeEnv('test');
+            await initializePsychicApplication();
+            await index_js_1.default.syncOpenapiJson();
+            process.exit();
+        });
+    }
+}
+exports.default = PsychicCLI;

package/dist/cjs/src/controller/decorators.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BeforeAction = BeforeAction;
+exports.OpenAPI = OpenAPI;
+const endpoint_js_1 = require("../openapi-renderer/endpoint.js");
+const hooks_js_1 = require("./hooks.js");
+function BeforeAction(opts = {}) {
+    return function (_, context) {
+        const methodName = context.name;
+        context.addInitializer(function () {
+            const psychicControllerClass = this.constructor;
+            if (!psychicControllerClass['globallyInitializingDecorators']) {
+                return;
+            }
+            if (!Object.getOwnPropertyDescriptor(psychicControllerClass, 'controllerHooks'))
+                psychicControllerClass.controllerHooks = [...psychicControllerClass.controllerHooks];
+            psychicControllerClass.controllerHooks.push(new hooks_js_1.ControllerHook(psychicControllerClass.name, methodName.toString(), opts));
+        });
+    };
+}
+/**
+ * Used to annotate your controller method in a way that enables
+ * Psychic to automatically generate an openapi spec for you. Using
+ * this feature, you can easily document your api in typescript, taking
+ * advantage of powerful type completion and validation, as well as useful
+ * shorthand notation to keep annotations simple when possible.
+ *
+ * @param modelOrSerializer - a function which immediately returns either a serializer class, a dream model class, or else something that has a serializers getter on it.
+ * @param body - Optional. The shape of the request body
+ * @param headers - Optional. The list of request headers to provide for this endpoint
+ * @param many - Optional. whether or not to render a top level array for this serializer
+ * @param method - The HTTP method to use when hitting this endpoint
+ * @param path - Optional. If passed, this path will be used as the request path. If not, it will be looked up in the conf/routes.ts file.
+ * @param query - Optional. A list of query params to provide for this endpoint
+ * @param responses - Optional. A list of additional responses that your app may return
+ * @param serializerKey - Optional. Use this to override the serializer key to use when looking up a serializer by the provided model or view model.
+ * @param status - Optional. The status code this endpoint uses when responding successfully. If not passed, 200 is assummed.
+ * @param tags - Optional. string array
+ * @param uri - Optional. A list of uri segments that this endpoint uses
+ */
+function OpenAPI(modelOrSerializer, opts) {
+    return function (_, context) {
+        const methodName = context.name;
+        context.addInitializer(function () {
+            const psychicControllerClass = this.constructor;
+            if (!psychicControllerClass['globallyInitializingDecorators']) {
+                return;
+            }
+            const methodNameString = methodName.toString();
+            if (!Object.getOwnPropertyDescriptor(psychicControllerClass, 'openapi'))
+                psychicControllerClass.openapi = {};
+            if (!Object.getOwnPropertyDescriptor(psychicControllerClass, 'controllerActionMetadata'))
+                psychicControllerClass['controllerActionMetadata'] = {};
+            if (opts) {
+                psychicControllerClass.openapi[methodNameString] = new endpoint_js_1.default(modelOrSerializer, psychicControllerClass, methodNameString, opts);
+                psychicControllerClass['controllerActionMetadata'][methodNameString] ||= {};
+                psychicControllerClass['controllerActionMetadata'][methodNameString]['serializerKey'] =
+                    opts.serializerKey;
+                //
+            }
+            else {
+                if (isSerializable(modelOrSerializer)) {
+                    psychicControllerClass.openapi[methodNameString] = new endpoint_js_1.default(modelOrSerializer, psychicControllerClass, methodNameString, undefined);
+                }
+                else {
+                    psychicControllerClass.openapi[methodNameString] = new endpoint_js_1.default(null, psychicControllerClass, methodNameString, modelOrSerializer);
+                }
+            }
+        });
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isSerializable(dreamOrSerializerClass) {
+    return (Array.isArray(dreamOrSerializerClass) ||
+        hasSerializersGetter(dreamOrSerializerClass) ||
+        !!dreamOrSerializerClass?.isDreamSerializer);
+}
+function hasSerializersGetter(dreamOrSerializerClass) {
+    try {
+        return !!dreamOrSerializerClass?.prototype?.serializers;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cjs/src/controller/hooks.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControllerHook = void 0;
+class ControllerHook {
+    controllerClassName;
+    methodName;
+    isStatic;
+    only;
+    except;
+    constructor(controllerClassName, methodName, { isStatic = false, only = [], except = [], }) {
+        this.controllerClassName = controllerClassName;
+        this.methodName = methodName;
+        this.isStatic = isStatic;
+        this.only = only;
+        this.except = except;
+    }
+    shouldFireForAction(actionName) {
+        if (!!this.only.length && this.only.includes(actionName))
+            return true;
+        if (!!this.only.length && !this.only.includes(actionName))
+            return false;
+        if (!!this.except.length && this.except.includes(actionName))
+            return false;
+        if (!!this.except.length && !this.except.includes(actionName))
+            return true;
+        return true;
+    }
+}
+exports.ControllerHook = ControllerHook;