@rvoh/psychic-workers 2.0.2 → 2.1.0

package/dist/cjs/src/background/BaseBackgroundedModel.js

@@ -92,8 +92,8 @@ export default class BaseBackgroundedModel extends Dream {
      * in psychic-workers.
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    get psychicTypes() {
-        throw new Error('Must define psychicTypes getter in BackgroundedService class within your application');
+    get psychicWorkerTypes() {
+        throw new Error('Must define psychicWorkerTypes getter in ApplicationBackgroundedModel class within your application');
     }
     /**
      * runs the specified method in a background queue, driven by BullMQ,

package/dist/cjs/src/background/BaseBackgroundedService.js

@@ -104,7 +104,7 @@ export default class BaseBackgroundedService {
      * in psychic-workers.
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    get psychicTypes() {
-        throw new Error('Must define psychicTypes getter in BackgroundedService class within your application');
+    get psychicWorkerTypes() {
+        throw new Error('Must define psychicWorkerTypes getter in ApplicationBackgroundedService class within your application');
     }
 }

package/dist/cjs/src/background/BaseScheduledService.js

@@ -73,7 +73,7 @@ export default class BaseScheduledService {
      * in psychic-workers.
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    get psychicTypes() {
-        throw new Error('Must define psychicTypes getter in BackgroundedService class within your application');
+    get psychicWorkerTypes() {
+        throw new Error('Must define psychicWorkerTypes getter in ApplicationScheduledService class within your application');
     }
 }

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

@@ -526,8 +526,6 @@ export class Background {
         if (!queueInstance)
             throw new Error(`missing queue: ${jobConfig?.queue?.toString() || 'N/A'}`);
         const jobOptions = {};
-        if (jobId)
-            jobOptions.jobId = jobId;
         if (delay)
             jobOptions.delay = delay;
         if (delay && jobId) {

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

@@ -0,0 +1,176 @@
+import { DreamApp } from '@rvoh/dream';
+import * as path from 'node:path';
+import ts from 'typescript';
+import PsychicAppWorkers from '../psychic-app-workers/index.js';
+const f = ts.factory;
+/**
+ * @internal
+ *
+ * This is a base class, which is inherited by the ASTSchemaBuilder,
+ * the ASTKyselyCodegenEnhancer, and the ASTGlobalSchemaBuilder,
+ * each of which is responsible for building up the output of the various
+ * type files consumed by dream internally.
+ *
+ * This base class is just a container for common methods used by all
+ * classes.
+ */
+export default class ASTBuilder {
+    /**
+     * @internal
+     *
+     * builds a new line, useful for injecting new lines into AST statements
+     */
+    newLine() {
+        return f.createIdentifier('\n');
+    }
+    /**
+     * @internal
+     *
+     * given an interface declaration, it will extrace the relevant property statement
+     * by the given property name.
+     */
+    getPropertyFromInterface(interfaceNode, propertyName) {
+        for (const member of interfaceNode.members) {
+            if (ts.isPropertySignature(member)) {
+                if (ts.isIdentifier(member.name) && member.name.text === propertyName) {
+                    return member;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns an array of string type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    extractStringLiteralTypeNodesFromTypeOrUnion(typeAlias) {
+        const literals = [];
+        if (ts.isUnionTypeNode(typeAlias.type)) {
+            typeAlias.type.types.forEach(typeNode => {
+                if (ts.isLiteralTypeNode(typeNode) && ts.isStringLiteral(typeNode.literal)) {
+                    literals.push(typeNode);
+                }
+            });
+        }
+        else if (ts.isLiteralTypeNode(typeAlias.type) && ts.isStringLiteral(typeAlias.type.literal)) {
+            literals.push(typeAlias.type);
+        }
+        return literals;
+    }
+    /**
+     * @internal
+     *
+     * returns an array of type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    extractTypeNodesFromTypeOrUnion(typeAlias) {
+        const literals = [];
+        if (typeAlias.type && ts.isUnionTypeNode(typeAlias.type)) {
+            typeAlias.type.types.forEach(typeNode => {
+                literals.push(typeNode);
+            });
+        }
+        else if (typeAlias.type) {
+            literals.push(typeAlias.type);
+        }
+        return literals;
+    }
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported type alias
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    exportedTypeAliasOrNull(node, exportName) {
+        if (ts.isTypeAliasDeclaration(node) &&
+            node?.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) &&
+            (!exportName ? true : node.name.text === exportName))
+            return node;
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported interface
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    exportedInterfaceOrNull(node, exportName) {
+        if (ts.isInterfaceDeclaration(node) &&
+            node?.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) &&
+            (!exportName ? true : node.name.text === exportName))
+            return node;
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns the path to the dream.globals.ts file
+     */
+    workersSchemaPath() {
+        const workersApp = PsychicAppWorkers.getOrFail();
+        return path.join(workersApp.psychicApp.apiRoot, DreamApp.getOrFail().paths.types, 'workers.ts');
+    }
+    /**
+     * @internal
+     *
+     * safely runs prettier against the provided output. If prettier
+     * is not installed, then the original output is returned
+     */
+    async prettier(output) {
+        try {
+            // dynamically, safely bring in prettier.
+            // ini the event that it fails, we will return the
+            // original output, unformatted, since prettier
+            // is technically not a real dependency of dream,
+            // though psychic and dream apps are provisioned
+            // with prettier by default, so this should usually work
+            const prettier = (await import('prettier')).default;
+            const results = await prettier.format(output, {
+                parser: 'typescript',
+                semi: false,
+                singleQuote: true,
+                tabWidth: 2,
+                lineWidth: 80,
+            });
+            return typeof results === 'string' ? results : output;
+        }
+        catch {
+            // intentional noop, we don't want to raise if prettier
+            // fails, since it is possible for the end user to not
+            // want to use prettier, and it is not a required peer
+            // dependency of dream
+            return output;
+        }
+    }
+    /**
+     * @internal
+     *
+     * given a type node, it will send back the first found generic
+     * provided to that type.
+     */
+    getFirstGenericType(node) {
+        if (ts.isTypeReferenceNode(node)) {
+            if (node.typeArguments && node.typeArguments.length > 0) {
+                return node.typeArguments[0];
+            }
+        }
+        else if (ts.isCallExpression(node)) {
+            if (node.typeArguments && node.typeArguments.length > 0) {
+                return node.typeArguments[0];
+            }
+        }
+        return null;
+    }
+}

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

@@ -0,0 +1,60 @@
+import { CliFileWriter, DreamCLI } from '@rvoh/dream/system';
+import ts from 'typescript';
+import background from '../background/index.js';
+import ASTBuilder from './ASTBuilder.js';
+const f = ts.factory;
+/**
+ * Responsible for building dream globals, which can be found at
+ * types/dream.globals.ts.
+ *
+ * This class leverages internal AST building mechanisms built into
+ * typescript to manually build up object literals and interfaces
+ * for our app to consume.
+ */
+export default class ASTWorkersSchemaBuilder extends ASTBuilder {
+    async build() {
+        const logger = DreamCLI.logger;
+        const sourceFile = ts.createSourceFile('', '', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+        await logger.logProgress('[psychic workers] building workers types', async () => {
+            const output = await this.prettier(this.printStatements(this.buildWorkersTypeConfigConst(), sourceFile));
+            await CliFileWriter.write(this.workersSchemaPath(), output);
+        });
+    }
+    /**
+     * @internal
+     *
+     * builds up the `export const globalTypeConfig = ...` statement within the types/workers.ts
+     * file. It does this by leveraging low-level AST utils built into typescript
+     * to manually build up an object literal, cast it as a const, and write it to
+     * an exported variable.
+     */
+    buildWorkersTypeConfigConst() {
+        background.connect();
+        const globalTypeConfigObjectLiteral = f.createObjectLiteralExpression([
+            f.createPropertyAssignment(f.createIdentifier('workstreamNames'), f.createArrayLiteralExpression(background['workstreamNames'].map(key => f.createStringLiteral(key)))),
+            f.createPropertyAssignment(f.createIdentifier('queueGroupMap'), f.createObjectLiteralExpression(Object.keys(background['groupNames']).map(key => f.createPropertyAssignment(f.createStringLiteral(key), f.createArrayLiteralExpression(background['groupNames'][key].map(str => f.createStringLiteral(str))))), true)),
+        ], true);
+        // add "as const" to the end of the schema object we
+        // have built before returning it
+        const constAssertion = f.createAsExpression(globalTypeConfigObjectLiteral, f.createKeywordTypeNode(ts.SyntaxKind.ConstKeyword));
+        const psychicWorkerTypesObjectLiteralConst = f.createVariableStatement(undefined, f.createVariableDeclarationList([
+            f.createVariableDeclaration(f.createIdentifier('psychicWorkerTypes'), undefined, undefined, constAssertion),
+        ], ts.NodeFlags.Const));
+        const defaultExportIdentifier = f.createIdentifier('psychicWorkerTypes');
+        const exportDefaultStatement = f.createExportDefault(defaultExportIdentifier);
+        return [psychicWorkerTypesObjectLiteralConst, this.newLine(), exportDefaultStatement];
+    }
+    /**
+     * @internal
+     *
+     * writes the compiled statements to string.
+     *
+     */
+    printStatements(statements, sourceFile) {
+        const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed, omitTrailingSemicolon: true });
+        const result = printer.printList(ts.ListFormat.SourceFileStatements, f.createNodeArray(statements), sourceFile);
+        // TODO: add autogenerate disclaimer
+        return `\
+${result}`;
+    }
+}

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

@@ -0,0 +1,67 @@
+import { DreamApp } from '@rvoh/dream';
+import { DreamCLI } from '@rvoh/dream/system';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import PsychicAppWorkers from '../psychic-app-workers/index.js';
+/**
+ * Originally, psychic-workers tapped into the types produced by psychic,
+ * modifying the psychicTypes to include type configurations for workers
+ * as well. Since Psychic no longer supports this method of augmenting
+ * types, psychic-workers has been refactored to produce its own types
+ * file.
+ *
+ * This service is responsible for identifying applications that are still
+ * reliant on the types produced by psychic, and refactoring them so that their
+ * imports are now in the correct places.
+ */
+export default class PsychicTypesDeprecation {
+    async deprecate() {
+        const workersApp = PsychicAppWorkers.getOrFail();
+        if (workersApp.bypassDeprecationChecks)
+            return;
+        const files = [
+            path.join(process.cwd(), DreamApp.system.dreamPath('models'), 'ApplicationBackgroundedModel.ts'),
+            path.join(process.cwd(), DreamApp.system.dreamPath('models'), '..', 'services', 'ApplicationBackgroundedService.ts'),
+            path.join(process.cwd(), DreamApp.system.dreamPath('models'), '..', 'services', 'ApplicationScheduledService.ts'),
+        ];
+        try {
+            for (const file of files) {
+                const fileContent = (await fs.readFile(file)).toString();
+                if (fileContent.includes('psychicTypes')) {
+                    await DreamCLI.logger.logProgress(`[psychic workers] patching deprecated types for ${file.split(path.sep).at(-1)}`, async () => {
+                        await fs.writeFile(file, fileContent
+                            .replace(/psychicTypes/g, 'psychicWorkerTypes')
+                            .replace(/types\/psychic\.js/, 'types/workers.js'));
+                    });
+                }
+            }
+        }
+        catch (err) {
+            console.error(err);
+            console.log(`
+ATTENTION: 
+
+The psychic-workers package now requires a new configuration in order to continue providing types
+in the modern psychic ecosystem. We attempted to automatically fix this for you, but something went
+wrong. Please locate the following files, and ensure that they no longer provide the "psychicTypes" getter.
+they should instead provide a psychicWorkerTypes getter in its place, which brings in types that
+are now located in the newly-generated "types/workers.ts" file.
+
+For the ApplicationBackgroundedModel.ts, ApplicationScheduledService.ts, and ApplicationBackgroundedService.ts 
+files in your system, ensure that their "psychicTypes" getter is replaced with the "psychicWorkerTypes"
+getter, like so:
+
+
+import { psychicWorkerTypes } from '@src/types/workers.js'
+
+export default class ApplicationBackgroundedModel extends BaseBackgroundedModel {
+  ...
+
+  public override get psychicWorkerTypes() {
+    return psychicWorkerTypes
+  }
+}
+`);
+        }
+    }
+}

package/dist/cjs/src/psychic-app-workers/index.js

@@ -1,17 +1,15 @@
 import { Queue, Worker } from 'bullmq';
-import { cachePsychicWorkersApp, getCachedPsychicWorkersAppOrFail } from './cache.js';
 import background from '../background/index.js';
+import ASTWorkersSchemaBuilder from '../cli/ASTWorkersSchemaBuilder.js';
+import PsychicTypesDeprecation from '../cli/PsychicTypesDeprecation.js';
+import { cachePsychicWorkersApp, getCachedPsychicWorkersAppOrFail } from './cache.js';
 export default class PsychicAppWorkers {
     static async init(psychicApp, cb) {
         const psychicWorkersApp = new PsychicAppWorkers(psychicApp);
         await cb(psychicWorkersApp);
-        psychicApp.on('cli:sync', () => {
-            background.connect();
-            const output = {
-                workstreamNames: [...background['workstreamNames']],
-                queueGroupMap: { ...background['groupNames'] },
-            };
-            return output;
+        psychicApp.on('cli:sync', async () => {
+            await new ASTWorkersSchemaBuilder().build();
+            await new PsychicTypesDeprecation().deprecate();
         });
         psychicApp.on('server:shutdown', async () => {
             await background.closeAllRedisConnections();
@@ -56,6 +54,16 @@ export default class PsychicAppWorkers {
         return this._testInvocation;
     }
     _testInvocation = 'automatic';
+    /**
+     * if set to true, it will bypass deprecation checks that run
+     * during the sync hook. Defaults to false, we only recommend
+     * overriding this if you are having issues with the deprecation
+     * check.
+     */
+    get bypassDeprecationChecks() {
+        return this._bypassDeprecationChecks;
+    }
+    _bypassDeprecationChecks = false;
     _hooks = {
         workerShutdown: [],
     };
@@ -87,6 +95,9 @@ export default class PsychicAppWorkers {
             case 'testInvocation':
                 this._testInvocation = value;
                 break;
+            case 'bypassDeprecationChecks':
+                this._bypassDeprecationChecks = value;
+                break;
             default:
                 throw new Error(`Unhandled option type passed to PsychicWorkersApp#set: ${option}`);
         }

package/dist/esm/src/background/BaseBackgroundedModel.js

@@ -92,8 +92,8 @@ export default class BaseBackgroundedModel extends Dream {
      * in psychic-workers.
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    get psychicTypes() {
-        throw new Error('Must define psychicTypes getter in BackgroundedService class within your application');
+    get psychicWorkerTypes() {
+        throw new Error('Must define psychicWorkerTypes getter in ApplicationBackgroundedModel class within your application');
     }
     /**
      * runs the specified method in a background queue, driven by BullMQ,

package/dist/esm/src/background/BaseBackgroundedService.js

@@ -104,7 +104,7 @@ export default class BaseBackgroundedService {
      * in psychic-workers.
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    get psychicTypes() {
-        throw new Error('Must define psychicTypes getter in BackgroundedService class within your application');
+    get psychicWorkerTypes() {
+        throw new Error('Must define psychicWorkerTypes getter in ApplicationBackgroundedService class within your application');
     }
 }

package/dist/esm/src/background/BaseScheduledService.js

@@ -73,7 +73,7 @@ export default class BaseScheduledService {
      * in psychic-workers.
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    get psychicTypes() {
-        throw new Error('Must define psychicTypes getter in BackgroundedService class within your application');
+    get psychicWorkerTypes() {
+        throw new Error('Must define psychicWorkerTypes getter in ApplicationScheduledService class within your application');
     }
 }

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

@@ -526,8 +526,6 @@ export class Background {
         if (!queueInstance)
             throw new Error(`missing queue: ${jobConfig?.queue?.toString() || 'N/A'}`);
         const jobOptions = {};
-        if (jobId)
-            jobOptions.jobId = jobId;
         if (delay)
             jobOptions.delay = delay;
         if (delay && jobId) {

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

@@ -0,0 +1,176 @@
+import { DreamApp } from '@rvoh/dream';
+import * as path from 'node:path';
+import ts from 'typescript';
+import PsychicAppWorkers from '../psychic-app-workers/index.js';
+const f = ts.factory;
+/**
+ * @internal
+ *
+ * This is a base class, which is inherited by the ASTSchemaBuilder,
+ * the ASTKyselyCodegenEnhancer, and the ASTGlobalSchemaBuilder,
+ * each of which is responsible for building up the output of the various
+ * type files consumed by dream internally.
+ *
+ * This base class is just a container for common methods used by all
+ * classes.
+ */
+export default class ASTBuilder {
+    /**
+     * @internal
+     *
+     * builds a new line, useful for injecting new lines into AST statements
+     */
+    newLine() {
+        return f.createIdentifier('\n');
+    }
+    /**
+     * @internal
+     *
+     * given an interface declaration, it will extrace the relevant property statement
+     * by the given property name.
+     */
+    getPropertyFromInterface(interfaceNode, propertyName) {
+        for (const member of interfaceNode.members) {
+            if (ts.isPropertySignature(member)) {
+                if (ts.isIdentifier(member.name) && member.name.text === propertyName) {
+                    return member;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns an array of string type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    extractStringLiteralTypeNodesFromTypeOrUnion(typeAlias) {
+        const literals = [];
+        if (ts.isUnionTypeNode(typeAlias.type)) {
+            typeAlias.type.types.forEach(typeNode => {
+                if (ts.isLiteralTypeNode(typeNode) && ts.isStringLiteral(typeNode.literal)) {
+                    literals.push(typeNode);
+                }
+            });
+        }
+        else if (ts.isLiteralTypeNode(typeAlias.type) && ts.isStringLiteral(typeAlias.type.literal)) {
+            literals.push(typeAlias.type);
+        }
+        return literals;
+    }
+    /**
+     * @internal
+     *
+     * returns an array of type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    extractTypeNodesFromTypeOrUnion(typeAlias) {
+        const literals = [];
+        if (typeAlias.type && ts.isUnionTypeNode(typeAlias.type)) {
+            typeAlias.type.types.forEach(typeNode => {
+                literals.push(typeNode);
+            });
+        }
+        else if (typeAlias.type) {
+            literals.push(typeAlias.type);
+        }
+        return literals;
+    }
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported type alias
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    exportedTypeAliasOrNull(node, exportName) {
+        if (ts.isTypeAliasDeclaration(node) &&
+            node?.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) &&
+            (!exportName ? true : node.name.text === exportName))
+            return node;
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported interface
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    exportedInterfaceOrNull(node, exportName) {
+        if (ts.isInterfaceDeclaration(node) &&
+            node?.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) &&
+            (!exportName ? true : node.name.text === exportName))
+            return node;
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns the path to the dream.globals.ts file
+     */
+    workersSchemaPath() {
+        const workersApp = PsychicAppWorkers.getOrFail();
+        return path.join(workersApp.psychicApp.apiRoot, DreamApp.getOrFail().paths.types, 'workers.ts');
+    }
+    /**
+     * @internal
+     *
+     * safely runs prettier against the provided output. If prettier
+     * is not installed, then the original output is returned
+     */
+    async prettier(output) {
+        try {
+            // dynamically, safely bring in prettier.
+            // ini the event that it fails, we will return the
+            // original output, unformatted, since prettier
+            // is technically not a real dependency of dream,
+            // though psychic and dream apps are provisioned
+            // with prettier by default, so this should usually work
+            const prettier = (await import('prettier')).default;
+            const results = await prettier.format(output, {
+                parser: 'typescript',
+                semi: false,
+                singleQuote: true,
+                tabWidth: 2,
+                lineWidth: 80,
+            });
+            return typeof results === 'string' ? results : output;
+        }
+        catch {
+            // intentional noop, we don't want to raise if prettier
+            // fails, since it is possible for the end user to not
+            // want to use prettier, and it is not a required peer
+            // dependency of dream
+            return output;
+        }
+    }
+    /**
+     * @internal
+     *
+     * given a type node, it will send back the first found generic
+     * provided to that type.
+     */
+    getFirstGenericType(node) {
+        if (ts.isTypeReferenceNode(node)) {
+            if (node.typeArguments && node.typeArguments.length > 0) {
+                return node.typeArguments[0];
+            }
+        }
+        else if (ts.isCallExpression(node)) {
+            if (node.typeArguments && node.typeArguments.length > 0) {
+                return node.typeArguments[0];
+            }
+        }
+        return null;
+    }
+}

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

@@ -0,0 +1,60 @@
+import { CliFileWriter, DreamCLI } from '@rvoh/dream/system';
+import ts from 'typescript';
+import background from '../background/index.js';
+import ASTBuilder from './ASTBuilder.js';
+const f = ts.factory;
+/**
+ * Responsible for building dream globals, which can be found at
+ * types/dream.globals.ts.
+ *
+ * This class leverages internal AST building mechanisms built into
+ * typescript to manually build up object literals and interfaces
+ * for our app to consume.
+ */
+export default class ASTWorkersSchemaBuilder extends ASTBuilder {
+    async build() {
+        const logger = DreamCLI.logger;
+        const sourceFile = ts.createSourceFile('', '', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+        await logger.logProgress('[psychic workers] building workers types', async () => {
+            const output = await this.prettier(this.printStatements(this.buildWorkersTypeConfigConst(), sourceFile));
+            await CliFileWriter.write(this.workersSchemaPath(), output);
+        });
+    }
+    /**
+     * @internal
+     *
+     * builds up the `export const globalTypeConfig = ...` statement within the types/workers.ts
+     * file. It does this by leveraging low-level AST utils built into typescript
+     * to manually build up an object literal, cast it as a const, and write it to
+     * an exported variable.
+     */
+    buildWorkersTypeConfigConst() {
+        background.connect();
+        const globalTypeConfigObjectLiteral = f.createObjectLiteralExpression([
+            f.createPropertyAssignment(f.createIdentifier('workstreamNames'), f.createArrayLiteralExpression(background['workstreamNames'].map(key => f.createStringLiteral(key)))),
+            f.createPropertyAssignment(f.createIdentifier('queueGroupMap'), f.createObjectLiteralExpression(Object.keys(background['groupNames']).map(key => f.createPropertyAssignment(f.createStringLiteral(key), f.createArrayLiteralExpression(background['groupNames'][key].map(str => f.createStringLiteral(str))))), true)),
+        ], true);
+        // add "as const" to the end of the schema object we
+        // have built before returning it
+        const constAssertion = f.createAsExpression(globalTypeConfigObjectLiteral, f.createKeywordTypeNode(ts.SyntaxKind.ConstKeyword));
+        const psychicWorkerTypesObjectLiteralConst = f.createVariableStatement(undefined, f.createVariableDeclarationList([
+            f.createVariableDeclaration(f.createIdentifier('psychicWorkerTypes'), undefined, undefined, constAssertion),
+        ], ts.NodeFlags.Const));
+        const defaultExportIdentifier = f.createIdentifier('psychicWorkerTypes');
+        const exportDefaultStatement = f.createExportDefault(defaultExportIdentifier);
+        return [psychicWorkerTypesObjectLiteralConst, this.newLine(), exportDefaultStatement];
+    }
+    /**
+     * @internal
+     *
+     * writes the compiled statements to string.
+     *
+     */
+    printStatements(statements, sourceFile) {
+        const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed, omitTrailingSemicolon: true });
+        const result = printer.printList(ts.ListFormat.SourceFileStatements, f.createNodeArray(statements), sourceFile);
+        // TODO: add autogenerate disclaimer
+        return `\
+${result}`;
+    }
+}

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

@@ -0,0 +1,67 @@
+import { DreamApp } from '@rvoh/dream';
+import { DreamCLI } from '@rvoh/dream/system';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import PsychicAppWorkers from '../psychic-app-workers/index.js';
+/**
+ * Originally, psychic-workers tapped into the types produced by psychic,
+ * modifying the psychicTypes to include type configurations for workers
+ * as well. Since Psychic no longer supports this method of augmenting
+ * types, psychic-workers has been refactored to produce its own types
+ * file.
+ *
+ * This service is responsible for identifying applications that are still
+ * reliant on the types produced by psychic, and refactoring them so that their
+ * imports are now in the correct places.
+ */
+export default class PsychicTypesDeprecation {
+    async deprecate() {
+        const workersApp = PsychicAppWorkers.getOrFail();
+        if (workersApp.bypassDeprecationChecks)
+            return;
+        const files = [
+            path.join(process.cwd(), DreamApp.system.dreamPath('models'), 'ApplicationBackgroundedModel.ts'),
+            path.join(process.cwd(), DreamApp.system.dreamPath('models'), '..', 'services', 'ApplicationBackgroundedService.ts'),
+            path.join(process.cwd(), DreamApp.system.dreamPath('models'), '..', 'services', 'ApplicationScheduledService.ts'),
+        ];
+        try {
+            for (const file of files) {
+                const fileContent = (await fs.readFile(file)).toString();
+                if (fileContent.includes('psychicTypes')) {
+                    await DreamCLI.logger.logProgress(`[psychic workers] patching deprecated types for ${file.split(path.sep).at(-1)}`, async () => {
+                        await fs.writeFile(file, fileContent
+                            .replace(/psychicTypes/g, 'psychicWorkerTypes')
+                            .replace(/types\/psychic\.js/, 'types/workers.js'));
+                    });
+                }
+            }
+        }
+        catch (err) {
+            console.error(err);
+            console.log(`
+ATTENTION: 
+
+The psychic-workers package now requires a new configuration in order to continue providing types
+in the modern psychic ecosystem. We attempted to automatically fix this for you, but something went
+wrong. Please locate the following files, and ensure that they no longer provide the "psychicTypes" getter.
+they should instead provide a psychicWorkerTypes getter in its place, which brings in types that
+are now located in the newly-generated "types/workers.ts" file.
+
+For the ApplicationBackgroundedModel.ts, ApplicationScheduledService.ts, and ApplicationBackgroundedService.ts 
+files in your system, ensure that their "psychicTypes" getter is replaced with the "psychicWorkerTypes"
+getter, like so:
+
+
+import { psychicWorkerTypes } from '@src/types/workers.js'
+
+export default class ApplicationBackgroundedModel extends BaseBackgroundedModel {
+  ...
+
+  public override get psychicWorkerTypes() {
+    return psychicWorkerTypes
+  }
+}
+`);
+        }
+    }
+}

package/dist/esm/src/psychic-app-workers/index.js

@@ -1,17 +1,15 @@
 import { Queue, Worker } from 'bullmq';
-import { cachePsychicWorkersApp, getCachedPsychicWorkersAppOrFail } from './cache.js';
 import background from '../background/index.js';
+import ASTWorkersSchemaBuilder from '../cli/ASTWorkersSchemaBuilder.js';
+import PsychicTypesDeprecation from '../cli/PsychicTypesDeprecation.js';
+import { cachePsychicWorkersApp, getCachedPsychicWorkersAppOrFail } from './cache.js';
 export default class PsychicAppWorkers {
     static async init(psychicApp, cb) {
         const psychicWorkersApp = new PsychicAppWorkers(psychicApp);
         await cb(psychicWorkersApp);
-        psychicApp.on('cli:sync', () => {
-            background.connect();
-            const output = {
-                workstreamNames: [...background['workstreamNames']],
-                queueGroupMap: { ...background['groupNames'] },
-            };
-            return output;
+        psychicApp.on('cli:sync', async () => {
+            await new ASTWorkersSchemaBuilder().build();
+            await new PsychicTypesDeprecation().deprecate();
         });
         psychicApp.on('server:shutdown', async () => {
             await background.closeAllRedisConnections();
@@ -56,6 +54,16 @@ export default class PsychicAppWorkers {
         return this._testInvocation;
     }
     _testInvocation = 'automatic';
+    /**
+     * if set to true, it will bypass deprecation checks that run
+     * during the sync hook. Defaults to false, we only recommend
+     * overriding this if you are having issues with the deprecation
+     * check.
+     */
+    get bypassDeprecationChecks() {
+        return this._bypassDeprecationChecks;
+    }
+    _bypassDeprecationChecks = false;
     _hooks = {
         workerShutdown: [],
     };
@@ -87,6 +95,9 @@ export default class PsychicAppWorkers {
             case 'testInvocation':
                 this._testInvocation = value;
                 break;
+            case 'bypassDeprecationChecks':
+                this._bypassDeprecationChecks = value;
+                break;
             default:
                 throw new Error(`Unhandled option type passed to PsychicWorkersApp#set: ${option}`);
         }

package/dist/types/src/background/BaseBackgroundedModel.d.ts

@@ -71,7 +71,7 @@ export default class BaseBackgroundedModel extends Dream {
      * metadata, which can be used to help provide types for the underlying methods
      * in psychic-workers.
      */
-    get psychicTypes(): any;
+    get psychicWorkerTypes(): any;
     /**
      * runs the specified method in a background queue, driven by BullMQ,
      * sending in the provided args.

package/dist/types/src/background/BaseBackgroundedService.d.ts

@@ -79,7 +79,7 @@ export default class BaseBackgroundedService {
      * metadata, which can be used to help provide types for the underlying methods
      * in psychic-workers.
      */
-    get psychicTypes(): any;
+    get psychicWorkerTypes(): any;
 }
 export type PsychicBackgroundedServiceStaticMethods<T extends typeof BaseBackgroundedService> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<typeof BaseBackgroundedService>>;
 export type PsychicBackgroundedServiceInstanceMethods<T extends BaseBackgroundedService> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<BaseBackgroundedService>>;

package/dist/types/src/background/BaseScheduledService.d.ts

@@ -57,6 +57,6 @@ export default class BaseScheduledService {
      * metadata, which can be used to help provide types for the underlying methods
      * in psychic-workers.
      */
-    get psychicTypes(): any;
+    get psychicWorkerTypes(): any;
 }
 export type PsychicScheduledServiceStaticMethods<T extends typeof BaseScheduledService> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<typeof BaseScheduledService>>;

package/dist/types/src/cli/ASTBuilder.d.ts

@@ -0,0 +1,89 @@
+import ts from 'typescript';
+/**
+ * @internal
+ *
+ * This is a base class, which is inherited by the ASTSchemaBuilder,
+ * the ASTKyselyCodegenEnhancer, and the ASTGlobalSchemaBuilder,
+ * each of which is responsible for building up the output of the various
+ * type files consumed by dream internally.
+ *
+ * This base class is just a container for common methods used by all
+ * classes.
+ */
+export default class ASTBuilder {
+    /**
+     * @internal
+     *
+     * builds a new line, useful for injecting new lines into AST statements
+     */
+    protected newLine(): ts.Identifier;
+    /**
+     * @internal
+     *
+     * given an interface declaration, it will extrace the relevant property statement
+     * by the given property name.
+     */
+    protected getPropertyFromInterface(interfaceNode: ts.InterfaceDeclaration, propertyName: string): ts.PropertySignature | null;
+    /**
+     * @internal
+     *
+     * returns an array of string type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    protected extractStringLiteralTypeNodesFromTypeOrUnion(typeAlias: ts.TypeAliasDeclaration): (ts.LiteralTypeNode & {
+        literal: {
+            text: string;
+        };
+    })[];
+    /**
+     * @internal
+     *
+     * returns an array of type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    protected extractTypeNodesFromTypeOrUnion(typeAlias: ts.TypeAliasDeclaration | ts.PropertySignature): ts.TypeNode[];
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported type alias
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    protected exportedTypeAliasOrNull(node: ts.Node, exportName?: string): ts.TypeAliasDeclaration | null;
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported interface
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    protected exportedInterfaceOrNull(node: ts.Node, exportName?: string): ts.InterfaceDeclaration | null;
+    /**
+     * @internal
+     *
+     * returns the path to the dream.globals.ts file
+     */
+    protected workersSchemaPath(): string;
+    /**
+     * @internal
+     *
+     * safely runs prettier against the provided output. If prettier
+     * is not installed, then the original output is returned
+     */
+    protected prettier(output: string): Promise<string>;
+    /**
+     * @internal
+     *
+     * given a type node, it will send back the first found generic
+     * provided to that type.
+     */
+    protected getFirstGenericType(node: ts.Node): ts.TypeNode | null;
+}

package/dist/types/src/cli/ASTWorkersSchemaBuilder.d.ts

@@ -0,0 +1,28 @@
+import ASTBuilder from './ASTBuilder.js';
+/**
+ * Responsible for building dream globals, which can be found at
+ * types/dream.globals.ts.
+ *
+ * This class leverages internal AST building mechanisms built into
+ * typescript to manually build up object literals and interfaces
+ * for our app to consume.
+ */
+export default class ASTWorkersSchemaBuilder extends ASTBuilder {
+    build(): Promise<void>;
+    /**
+     * @internal
+     *
+     * builds up the `export const globalTypeConfig = ...` statement within the types/workers.ts
+     * file. It does this by leveraging low-level AST utils built into typescript
+     * to manually build up an object literal, cast it as a const, and write it to
+     * an exported variable.
+     */
+    private buildWorkersTypeConfigConst;
+    /**
+     * @internal
+     *
+     * writes the compiled statements to string.
+     *
+     */
+    private printStatements;
+}

package/dist/types/src/cli/PsychicTypesDeprecation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Originally, psychic-workers tapped into the types produced by psychic,
+ * modifying the psychicTypes to include type configurations for workers
+ * as well. Since Psychic no longer supports this method of augmenting
+ * types, psychic-workers has been refactored to produce its own types
+ * file.
+ *
+ * This service is responsible for identifying applications that are still
+ * reliant on the types produced by psychic, and refactoring them so that their
+ * imports are now in the correct places.
+ */
+export default class PsychicTypesDeprecation {
+    deprecate(): Promise<void>;
+}

package/dist/types/src/psychic-app-workers/index.d.ts

@@ -30,16 +30,24 @@ export default class PsychicAppWorkers {
      */
     get testInvocation(): PsychicWorkersAppTestInvocationType;
     private _testInvocation;
+    /**
+     * if set to true, it will bypass deprecation checks that run
+     * during the sync hook. Defaults to false, we only recommend
+     * overriding this if you are having issues with the deprecation
+     * check.
+     */
+    get bypassDeprecationChecks(): boolean;
+    private _bypassDeprecationChecks;
     private _hooks;
     get hooks(): PsychicWorkersAppHooks;
     on<T extends PsychicWorkersHookEventType>(hookEventType: T, cb: T extends 'workers:shutdown' ? () => void | Promise<void> : never): void;
-    set<Opt extends PsychicWorkersAppOption>(option: Opt, value: Opt extends 'background' ? PsychicBackgroundOptions : Opt extends 'testInvocation' ? PsychicWorkersAppTestInvocationType : unknown): void;
+    set<Opt extends PsychicWorkersAppOption>(option: Opt, value: Opt extends 'background' ? PsychicBackgroundOptions : Opt extends 'testInvocation' ? PsychicWorkersAppTestInvocationType : Opt extends 'bypassDeprecationChecks' ? boolean : unknown): void;
 }
 export interface PsychicWorkersTypeSync {
     workstreamNames: string[];
     queueGroupMap: Record<string, string[]>;
 }
-export type PsychicWorkersAppOption = 'background' | 'testInvocation';
+export type PsychicWorkersAppOption = 'background' | 'testInvocation' | 'bypassDeprecationChecks';
 export type PsychicWorkersAppTestInvocationType = 'automatic' | 'manual';
 export type PsychicWorkersHookEventType = 'workers:shutdown';
 export interface PsychicWorkersAppHooks {

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

@@ -49,9 +49,9 @@ interface BaseBackgroundJobConfig {
     priority?: BackgroundQueuePriority;
 }
 export interface WorkstreamBackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService> extends BaseBackgroundJobConfig {
-    workstream?: T['psychicTypes']['workstreamNames'][number];
+    workstream?: T['psychicWorkerTypes']['workstreamNames'][number];
 }
-export interface QueueBackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService, PsyTypes extends T['psychicTypes'] = T['psychicTypes'], QueueGroupMap = PsyTypes['queueGroupMap'], Queue extends keyof QueueGroupMap & string = keyof QueueGroupMap & string, Groups extends QueueGroupMap[Queue] = QueueGroupMap[Queue], GroupId = Groups[number & keyof Groups]> extends BaseBackgroundJobConfig {
+export interface QueueBackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService, WorkerTypes extends T['psychicWorkerTypes'] = T['psychicWorkerTypes'], QueueGroupMap = WorkerTypes['queueGroupMap'], Queue extends keyof QueueGroupMap & string = keyof QueueGroupMap & string, Groups extends QueueGroupMap[Queue] = QueueGroupMap[Queue], GroupId = Groups[number & keyof Groups]> extends BaseBackgroundJobConfig {
     groupId?: GroupId;
     queue?: Queue;
 }

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic-workers",
   "description": "Background job system for Psychic applications",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "author": "RVO Health",
   "repository": {
     "type": "git",
@@ -84,7 +84,7 @@
     "supertest": "^7.1.4",
     "tslib": "^2.7.0",
     "tsx": "^4.20.6",
-    "typedoc": "^0.26.6",
+    "typedoc": "^0.28.15",
     "typescript": "^5.8.2",
     "typescript-eslint": "=7.18.0",
     "vitest": "^4.0.10"