@rvoh/psychic 0.24.1

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

@@ -0,0 +1,6 @@
+export type UUID = string;
+export type PsychicHookEventType = 'boot' | 'sync' | 'load' | 'load:dev' | 'load:prod' | 'load:test' | 'server:init' | 'server:init:after-routes' | 'server:start' | 'server:error' | 'server:shutdown';
+export type PsychicHookLoadEventTypes = Exclude<PsychicHookEventType, 'server:error' | 'server:init' | 'server:init:after-routes' | 'server:start' | 'server:shutdown' | 'sync'>;
+type Only<T, U> = T & Partial<Record<Exclude<keyof U, keyof T>, never>>;
+export type Either<T, U> = Only<T, U> | Only<U, T>;
+export {};

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

@@ -0,0 +1,26 @@
+import PsychicController from '../controller/index.js';
+import { FunctionPropertyNames } from '../helpers/typeHelpers.js';
+import PsychicRouter, { PsychicNestedRouter } from '../router/index.js';
+import { ResourcesMethodType, ResourcesOptions } from './types.js';
+export declare function routePath(routePath: string): string;
+export declare function resourcePath(routePath: string): string;
+export declare function sanitizedControllerPath(controllerName: string): string;
+export declare function controllerGlobalNameFromControllerPath(controllerName: string): string;
+export declare function namespacedRoute(namespace: string, route: string): string;
+export declare function namespacedControllerActionString(namespace: string, controllerActionString: string): string;
+type RoutingMechanism = PsychicRouter | PsychicNestedRouter;
+type LookupOpts = {
+    resourceName?: string;
+    httpMethod: string;
+    path: string;
+};
+export declare function lookupControllerOrFail(routingMechanism: RoutingMechanism, opts: LookupOpts): typeof PsychicController;
+export type PsychicControllerActions<T extends typeof PsychicController> = Exclude<FunctionPropertyNames<Required<InstanceType<T>>>, FunctionPropertyNames<PsychicController>>;
+export interface NamespaceConfig {
+    namespace: string;
+    resourceful: boolean;
+    isScope: boolean;
+}
+export declare function applyResourcesAction(path: string, action: ResourcesMethodType, routingMechanism: RoutingMechanism, options?: ResourcesOptions): void;
+export declare function applyResourceAction(path: string, action: ResourcesMethodType, routingMechanism: PsychicRouter | PsychicNestedRouter, options?: ResourcesOptions): void;
+export {};

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

@@ -0,0 +1,55 @@
+import { Application, Request, Response, Router } from 'express';
+import PsychicController from '../controller/index.js';
+import PsychicApplication from '../psychic-application/index.js';
+import { NamespaceConfig, PsychicControllerActions } from '../router/helpers.js';
+import RouteManager from './route-manager.js';
+import { HttpMethod, ResourcesOptions } from './types.js';
+export default class PsychicRouter {
+    app: Application;
+    config: PsychicApplication;
+    currentNamespaces: NamespaceConfig[];
+    routeManager: RouteManager;
+    constructor(app: Application, config: PsychicApplication);
+    get routingMechanism(): Application | Router;
+    get routes(): import("./route-manager.js").RouteConfig[];
+    private get currentNamespacePaths();
+    commit(): void;
+    get(path: string): void;
+    get<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
+    post(path: string): void;
+    post<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
+    put(path: string): void;
+    put<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
+    patch(path: string): void;
+    patch<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
+    delete(path: string): void;
+    delete<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
+    options(path: string): void;
+    options<T extends typeof PsychicController>(path: string, controller: T, action: PsychicControllerActions<T>): void;
+    private prefixPathWithNamespaces;
+    crud(httpMethod: HttpMethod, path: string): void;
+    crud(httpMethod: HttpMethod, path: string, controller: typeof PsychicController, action: string): void;
+    namespace(namespace: string, cb: (router: PsychicNestedRouter) => void): void;
+    scope(scope: string, cb: (router: PsychicNestedRouter) => void): void;
+    resources(path: string, optionsOrCb?: ResourcesOptions | ((router: PsychicNestedRouter) => void), cb?: (router: PsychicNestedRouter) => void): void;
+    resource(path: string, optionsOrCb?: ResourcesOptions | ((router: PsychicNestedRouter) => void), cb?: (router: PsychicNestedRouter) => void): void;
+    collection(cb: (router: PsychicNestedRouter) => void): void;
+    private makeResource;
+    private _makeResource;
+    private runNestedCallbacks;
+    private addNamespace;
+    private removeLastNamespace;
+    private makeRoomForNewIdParam;
+    handle(controller: typeof PsychicController, action: string, { req, res, }: {
+        req: Request;
+        res: Response;
+    }): Promise<void>;
+    _initializeController(ControllerClass: typeof PsychicController, req: Request, res: Response, action: string): PsychicController;
+}
+export declare class PsychicNestedRouter extends PsychicRouter {
+    router: Router;
+    constructor(app: Application, config: PsychicApplication, routeManager: RouteManager, { namespaces, }?: {
+        namespaces?: NamespaceConfig[];
+    });
+    get routingMechanism(): Router;
+}

package/dist/types/src/router/route-manager.d.ts

@@ -0,0 +1,17 @@
+import PsychicController from '../controller/index.js';
+import { HttpMethod } from './types.js';
+export default class RouteManager {
+    routes: RouteConfig[];
+    addRoute({ httpMethod, path, controller, action, }: {
+        httpMethod: HttpMethod;
+        path: string;
+        controller: typeof PsychicController;
+        action: string;
+    }): void;
+}
+export interface RouteConfig {
+    controller: typeof PsychicController;
+    action: string;
+    path: string;
+    httpMethod: HttpMethod;
+}

package/dist/types/src/router/types.d.ts

@@ -0,0 +1,11 @@
+import PsychicController from '../controller/index.js';
+export type ResourcesMethodType = 'index' | 'create' | 'update' | 'show' | 'destroy';
+export declare const ResourcesMethods: ResourcesMethodType[];
+export declare const ResourceMethods: ResourcesMethodType[];
+export declare const HttpMethods: readonly ["get", "post", "put", "patch", "delete", "options"];
+export type HttpMethod = (typeof HttpMethods)[number];
+export interface ResourcesOptions {
+    only?: ResourcesMethodType[];
+    except?: ResourcesMethodType[];
+    controller?: typeof PsychicController;
+}

package/dist/types/src/server/front-end-client.d.ts

@@ -0,0 +1,5 @@
+export default class FrontEndClientServer {
+    private child;
+    start(port?: number): void;
+    stop(): void;
+}

package/dist/types/src/server/helpers/startPsychicServer.d.ts

@@ -0,0 +1,14 @@
+import { Application } from 'express';
+import * as http from 'http';
+import { Server } from 'http';
+import * as https from 'https';
+import { PsychicSslCredentials } from '../../psychic-application/index.js';
+export interface StartPsychicServerOptions {
+    app: Application;
+    port: number;
+    withFrontEndClient: boolean;
+    frontEndPort: number;
+    sslCredentials: PsychicSslCredentials | undefined;
+}
+export default function startPsychicServer({ app, port, withFrontEndClient, frontEndPort, sslCredentials, }: StartPsychicServerOptions): Promise<Server>;
+export declare function createPsychicHttpInstance(app: Application, sslCredentials: PsychicSslCredentials | undefined): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse> | https.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;

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

@@ -0,0 +1,34 @@
+import { Application } from 'express';
+import { Server } from 'http';
+import PsychicApplication, { PsychicSslCredentials } from '../psychic-application/index.js';
+import FrontEndClientServer from './front-end-client.js';
+import { StartPsychicServerOptions } from './helpers/startPsychicServer.js';
+export default class PsychicServer {
+    static startPsychicServer(opts: StartPsychicServerOptions): Promise<Server>;
+    static createPsychicHttpInstance(app: Application, sslCredentials: PsychicSslCredentials | undefined): Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse> | import("https").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
+    static asciiLogo(): string;
+    expressApp: Application;
+    frontEndClient: FrontEndClientServer;
+    httpServer: Server;
+    private booted;
+    constructor();
+    get config(): PsychicApplication;
+    routes(): Promise<import("../router/route-manager.js").RouteConfig[]>;
+    boot(): Promise<true | undefined>;
+    start(port?: number, { withFrontEndClient, frontEndPort, }?: {
+        withFrontEndClient?: boolean;
+        frontEndPort?: number;
+    }): Promise<boolean>;
+    attach(id: string, obj: any): void;
+    $attached: Record<string, any>;
+    private shutdownAndExit;
+    stop({ bypassClosingDbConnections }?: {
+        bypassClosingDbConnections?: boolean;
+    }): Promise<void>;
+    serveForRequestSpecs(block: () => void | Promise<void>): Promise<boolean>;
+    buildApp(): void;
+    private initializeCors;
+    private initializeJSON;
+    private initializeOpenapiValidation;
+    private buildRoutes;
+}

package/dist/types/src/server/params.d.ts

@@ -0,0 +1,80 @@
+import { CalendarDate, Dream, DreamParamSafeAttributes, DreamParamSafeColumnNames } from '@rvoh/dream';
+import { DateTime } from 'luxon';
+import { PsychicParamsDictionary, PsychicParamsPrimitive, PsychicParamsPrimitiveLiterals } from '../controller/index.js';
+export default class Params {
+    /**
+     * ### .for
+     *
+     * given an object with key value pairs, it will validate
+     * each field based on the underlying schema of the passed dream model class
+     *
+     * ```ts
+     *
+     * // from within your controller...
+     *
+     * // raise error if not matching attributes for User model
+     * const params = Params.for(this.params.user, User)
+     * ```
+     */
+    static for<T extends typeof Dream, I extends InstanceType<T>, const OnlyArray extends readonly (keyof DreamParamSafeAttributes<I>)[], ForOpts extends ParamsForOpts<OnlyArray>, ParamSafeColumnsOverride extends I['paramSafeColumns' & keyof I] extends never ? undefined : I['paramSafeColumns' & keyof I] & string[], ParamSafeColumns extends ParamSafeColumnsOverride extends string[] | Readonly<string[]> ? Extract<DreamParamSafeColumnNames<I>, ParamSafeColumnsOverride[number] & DreamParamSafeColumnNames<I>>[] : DreamParamSafeColumnNames<I>[], ReturnPartialType extends ForOpts['only'] extends readonly (keyof DreamParamSafeAttributes<InstanceType<T>>)[] ? Partial<{
+        [K in Extract<ParamSafeColumns[number], ForOpts['only'][number & keyof ForOpts['only']]>]: DreamParamSafeAttributes<InstanceType<T>>[K];
+    }> : Partial<{
+        [K in ParamSafeColumns[number & keyof ParamSafeColumns] & string]: DreamParamSafeAttributes<InstanceType<T>>[K & keyof DreamParamSafeAttributes<InstanceType<T>>];
+    }>, ReturnPayload extends ForOpts['array'] extends true ? ReturnPartialType[] : ReturnPartialType>(params: object, dreamClass: T, forOpts?: ForOpts): ReturnPayload;
+    static restrict<T extends typeof Params>(this: T, params: PsychicParamsPrimitive | PsychicParamsDictionary | PsychicParamsDictionary[], allowed: string[]): PsychicParamsDictionary;
+    /**
+     * ### .cast
+     *
+     * Returns the param requested if it passes validation
+     * for the type specified. If the param is not of the type
+     * specified, an error is raised.
+     *
+     * ```ts
+     *
+     * // from within your controller...
+     *
+     * // raise error if not string
+     * Params.cast(this.params.id, 'string')
+     *
+     * // raise error if not number
+     * Params.cast(this.params.amount, 'number')
+     *
+     * // raise error if not array of integers
+     * Params.cast(this.params.amounts, 'integer[]')
+     *
+     * // raise error if not 'chalupas' or 'other'
+     * Params.cast(this.params.stuff, 'string', { enum: ['chalupas', 'other'] })
+     * ```
+     */
+    static cast<const EnumType extends readonly string[], OptsType extends ParamsCastOptions<EnumType>, ExpectedType extends (typeof PsychicParamsPrimitiveLiterals)[number] | RegExp, ValidatedType extends ValidatedReturnType<ExpectedType, OptsType>, AllowNullOrUndefined extends ValidatedAllowsNull<ExpectedType, OptsType>, FinalReturnType extends AllowNullOrUndefined extends true ? ValidatedType | null | undefined : ValidatedType>(param: PsychicParamsPrimitive, expectedType: ExpectedType, opts?: OptsType): FinalReturnType;
+    static casing<T extends typeof Params>(this: T, casing: 'snake' | 'camel'): Params;
+    private _casing;
+    constructor();
+    casing(casing: 'snake' | 'camel'): this;
+    cast<EnumType extends readonly string[], OptsType extends ParamsCastOptions<EnumType>, ExpectedType extends (typeof PsychicParamsPrimitiveLiterals)[number] | RegExp, ValidatedType extends ValidatedReturnType<ExpectedType, OptsType>, AllowNullOrUndefined extends ValidatedAllowsNull<ExpectedType, OptsType>, ReturnType extends AllowNullOrUndefined extends true ? ValidatedType | null | undefined : ValidatedType>(paramValue: PsychicParamsPrimitive | PsychicParamsDictionary | PsychicParamsDictionary[], expectedType: ExpectedType, opts?: OptsType): AllowNullOrUndefined extends true ? ValidatedType | null | undefined : ValidatedType;
+    restrict(param: PsychicParamsPrimitive | PsychicParamsDictionary | PsychicParamsDictionary[], allowed: string[]): PsychicParamsDictionary;
+    private matchRegexOrThrow;
+    private throwUnlessAllowNull;
+    private throw;
+}
+export declare class ParamValidationError extends Error {
+}
+export type ValidatedReturnType<ExpectedType, OptsType> = ExpectedType extends RegExp ? string : ExpectedType extends 'string' ? OptsType extends {
+    enum: infer EnumValue;
+} ? EnumValue extends readonly string[] ? EnumValue[number] : never : string : ExpectedType extends 'number' ? number : ExpectedType extends 'datetime' ? DateTime : ExpectedType extends 'date' ? CalendarDate : ExpectedType extends 'bigint' ? string : ExpectedType extends 'integer' ? number : ExpectedType extends 'json' ? object : ExpectedType extends 'boolean' ? boolean : ExpectedType extends 'null' ? null : ExpectedType extends 'uuid' ? string : ExpectedType extends 'datetime[]' ? DateTime[] : ExpectedType extends 'date[]' ? CalendarDate[] : ExpectedType extends 'string[]' ? OptsType extends {
+    enum: infer EnumValue;
+} ? EnumValue extends readonly string[] ? EnumValue[number][] : never : string[] : ExpectedType extends 'bigint[]' ? string[] : ExpectedType extends 'number[]' ? number[] : ExpectedType extends 'integer[]' ? number[] : ExpectedType extends 'boolean[]' ? boolean : ExpectedType extends 'null[]' ? null[] : ExpectedType extends 'uuid[]' ? string[] : never;
+export type ValidatedAllowsNull<ExpectedType, OptsValue> = ExpectedType extends {
+    allowNull: infer R;
+} ? R extends true ? true : R extends false ? false : never : OptsValue extends {
+    allowNull: infer RR;
+} ? RR extends true ? true : RR extends false ? false : never : false;
+export type ParamsCastOptions<EnumType> = {
+    allowNull?: boolean;
+    match?: RegExp;
+    enum?: EnumType;
+};
+export interface ParamsForOpts<OnlyArray> {
+    array?: boolean;
+    only?: OnlyArray;
+}

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

@@ -0,0 +1,12 @@
+import { CookieOptions, Request, Response } from 'express';
+import { CustomCookieOptions } from '../psychic-application/index.js';
+export default class Session {
+    private req;
+    private res;
+    constructor(req: Request, res: Response);
+    getCookie(name: string): unknown;
+    setCookie(name: string, data: string, opts?: CustomSessionCookieOptions): void;
+    clearCookie(name: string): void;
+    daysToMilliseconds(numDays: number): number;
+}
+export type CustomSessionCookieOptions = Omit<CookieOptions, 'maxAge'> & CustomCookieOptions;

package/package.json

@@ -0,0 +1,98 @@
+{
+  "type": "module",
+  "name": "@rvoh/psychic",
+  "description": "Typescript web framework",
+  "version": "0.24.1",
+  "author": "RVOHealth",
+  "repository": "https://github.com/rvohealth/psychic.git",
+  "license": "MIT",
+  "main": "./dist/cjs/src/index.js",
+  "module": "./dist/esm/src/index.js",
+  "types": "./dist/types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/esm/src/index.js",
+      "require": "./dist/cjs/src/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "client": "yarn --cwd=./client start",
+    "psy": "yarn psyts",
+    "psyjs": "node ./dist/test-app/src/cli/index.js",
+    "psyts": "node --experimental-specifier-resolution=node --import=./node/esm.js ./test-app/src/cli/index.ts",
+    "psycore": "PSYCHIC_CORE_DEVELOPMENT=1 yarn psyts",
+    "gpsycore": "PSYCHIC_CORE_DEVELOPMENT=1 npx ts-node --transpile-only ./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:core": "rm -rf dist && echo \"building core app to esm...\" && npx tsc -p ./tsconfig.esm.build.core.json && echo \"building core app to cjs...\" && npx tsc -p ./tsconfig.cjs.build.core.json",
+    "sync": "NODE_ENV=development yarn --cwd=node_modules/@rvohealth/dream build-boot && NODE_ENV=development yarn --cwd=node_modules/@rvohealth/dream build",
+    "syncb": "NODE_ENV=development yarn --cwd=node_modules/@rvohealth/dream build-boot && NODE_ENV=development yarn dream sync:config-cache && yarn --cwd=node_modules/@rvohealth/dream build && yarn build",
+    "dev": "PSYCHIC_CORE_DEVELOPMENT=1 NODE_ENV=development ts-node ./test-app/main.ts",
+    "console": "PSYCHIC_CORE_DEVELOPMENT=1 npx ts-node --transpile-only --project ./tsconfig.json ./test-app/src/conf/repl.ts",
+    "uspec": "PSYCHIC_CORE_DEVELOPMENT=1 vitest --config ./spec/unit/vite.config.ts",
+    "fspec": "PSYCHIC_CORE_DEVELOPMENT=1 vitest run --config=./spec/features/vite.config.ts",
+    "format": "yarn run prettier . --write",
+    "lint": "yarn run eslint --no-warn-ignored \"src/**/*.ts\" \"spec/**/*.ts\" \"test-app/**/*.ts\" && yarn run prettier . --check",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "@types/cookie-parser": "^1.4.7",
+    "@types/cors": "^2.8.17",
+    "@types/lodash.groupby": "^4.6.9",
+    "colorette": "^2.0.20",
+    "commander": "^12.1.0",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express-openapi-validator": "^5.4.3",
+    "iso-datestring-validator": "^2.2.2",
+    "lodash-es": "^4.17.21",
+    "lodash.clonedeep": "^4.5.0",
+    "lodash.groupby": "^4.6.0",
+    "pluralize-esm": "^9.0.5"
+  },
+  "peerDependencies": {
+    "@rvohealth/dream": "*",
+    "@types/express": "*",
+    "commander": "*",
+    "express": "*"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.19.0",
+    "@jest-mock/express": "^3.0.0",
+    "@rvoh/dream": "^0.29.1",
+    "@rvoh/dream-spec-helpers": "=0.1.0",
+    "@rvoh/psychic-spec-helpers": "=0.2.0",
+    "@types/express": "^4.17.21",
+    "@types/lodash-es": "^4",
+    "@types/lodash.clonedeep": "^4.5.9",
+    "@types/lodash.sortby": "^4.7.9",
+    "@types/luxon": "^3.4.2",
+    "@types/node": "^22.5.1",
+    "@types/pg": "^8.11.8",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.19.0",
+    "express": "^4.21.1",
+    "jsdom": "^26.0.0",
+    "kysely": "^0.27.4",
+    "kysely-codegen": "~0.17.0",
+    "lodash.sortby": "^4.7.0",
+    "luxon": "^3.5.0",
+    "luxon-jest-matchers": "^0.1.14",
+    "pg": "^8.12.0",
+    "prettier": "^3.3.3",
+    "puppeteer": "^24.4.0",
+    "supertest": "^7.0.0",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.7.0",
+    "typedoc": "^0.26.6",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "=7.18.0",
+    "vitest": "^3.0.8",
+    "winston": "^3.14.2"
+  },
+  "packageManager": "yarn@4.4.1"
+}