@rvoh/dream 2.0.4 → 2.1.0

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

@@ -0,0 +1,284 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import ts from 'typescript';
+import dbTypesFilenameForConnection from '../../db/helpers/dbTypesFilenameForConnection.js';
+import dreamSchemaTypesFilenameForConnection from '../../db/helpers/dreamSchemaTypesFilenameForConnection.js';
+import DreamApp from '../../dream-app/index.js';
+import Query from '../../dream/Query.js';
+import { ExplicitForeignKeyRequired, InvalidComputedForeignKey, } from '../../errors/associations/InvalidComputedForeignKey.js';
+import FailedToIdentifyAssociation from '../../errors/schema-builder/FailedToIdentifyAssociation.js';
+import intersection from '../intersection.js';
+import sortBy from '../sortBy.js';
+import uniq from '../uniq.js';
+import ASTBuilder from './ASTBuilder.js';
+/**
+ * @internal
+ *
+ * This is a base class, which is inherited by the ASTSchemaBuilder and
+ * the ASTKyselyCodegenEnhancer, both 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 both
+ * classes. It requires a connectionName to be provided, unlike the underlying
+ * ASTBuilder class, and provides methods which leverage the connectionName
+ *
+ */
+export default class ASTConnectionBuilder extends ASTBuilder {
+    connectionName;
+    hasForeignKeyError = false;
+    constructor(connectionName) {
+        super();
+        this.connectionName = connectionName;
+    }
+    /**
+     * @internal
+     *
+     * returns the path from project root to the dream.ts file
+     * for the particular connection. If the connectionName is anything
+     * other than default, the path will represent that by injecting
+     * the connectionName into the file name, i.e. dream.alternate.ts
+     */
+    schemaPath() {
+        const dreamApp = DreamApp.getOrFail();
+        return path.join(dreamApp.projectRoot, dreamApp.paths.types, dreamSchemaTypesFilenameForConnection(this.connectionName));
+    }
+    /**
+     * @internal
+     *
+     * returns the path from project root to the db.ts file
+     * for the particular connection. If the connectionName is anything
+     * other than default, the path will represent that by injecting
+     * the connectionName into the file name, i.e. db.alternate.ts
+     */
+    dbPath() {
+        const dreamApp = DreamApp.getOrFail();
+        return path.join(dreamApp.projectRoot, dreamApp.paths.types, dbTypesFilenameForConnection(this.connectionName));
+    }
+    /**
+     * @internal
+     *
+     * returns the db source file for the given connectionName, injecting
+     * the source file with the actual file contents, so that AST nodes
+     * can be built through ingesting.
+     */
+    async getDbSourceFile() {
+        const fileContent = await this.loadDbSyncFile();
+        return ts.createSourceFile('./db.js', fileContent, ts.ScriptTarget.Latest, true);
+    }
+    /**
+     * @internal
+     *
+     * reads the db source file for the given connection, returning the contents
+     * as a raw string
+     */
+    async loadDbSyncFile() {
+        return (await fs.readFile(this.dbPath())).toString();
+    }
+    /**
+     * @internal
+     *
+     * builds up the schema data for every table into an object, which
+     * can be read and injected into AST nodes.
+     */
+    async getSchemaData() {
+        const tables = await this.getTables();
+        const schemaData = {};
+        for (const table of tables) {
+            schemaData[table] = await this.tableData(table);
+        }
+        return schemaData;
+    }
+    /**
+     * @internal
+     *
+     * used by getSchemaData to build up all table data
+     */
+    async getTables() {
+        const fileContents = await this.loadDbSyncFile();
+        const tableLines = /export interface DB {([^}]*)}/.exec(fileContents)[1];
+        if (tableLines === undefined)
+            return [];
+        const tables = tableLines
+            .split('\n')
+            .map(line => {
+            const stingArray = line.split(':');
+            const substring = stingArray[0];
+            if (substring === undefined)
+                return '';
+            return substring.replace(/\s*/, '');
+        })
+            .filter(line => !!line);
+        return tables;
+    }
+    /**
+     * @internal
+     *
+     * finds all enums used by the app, and returns information
+     * about those enums that can be used for type generating purpposes
+     */
+    async getAllEnumValueNames() {
+        const schemaData = await this.getSchemaData();
+        const enumValueNames = Object.values(schemaData)
+            .map(tableData => Object.keys(tableData.columns)
+            .filter(columnName => !!tableData.columns[columnName]?.enumValues)
+            .map(columnName => ({
+            enumValues: tableData.columns[columnName].enumValues,
+            enumType: tableData.columns[columnName].enumType,
+        })))
+            .flat();
+        return enumValueNames;
+    }
+    /**
+     * @internal
+     *
+     * returns a tuple, where the first value is the global name, and the second value
+     * is the table that that global name points to. Used to build up our global
+     * model name exports within type files.
+     */
+    globalModelNames() {
+        const dreamApp = DreamApp.getOrFail();
+        const models = dreamApp.models;
+        return Object.keys(models)
+            .filter(key => models[key]?.prototype?.connectionName === this.connectionName)
+            .map(key => [key, models[key].prototype.table]);
+    }
+    /**
+     * @internal
+     *
+     * retrieves useful association data for a given association and table, which
+     * can be used to build up types
+     */
+    getAssociationData(tableName, targetAssociationType) {
+        const dreamApp = DreamApp.getOrFail();
+        const models = sortBy(Object.values(dreamApp.models), m => m.table);
+        const tableAssociationData = {};
+        for (const model of models.filter(model => model.table === tableName)) {
+            for (const associationName of model.associationNames) {
+                const associationMetaData = model['associationMetadataMap']()[associationName];
+                if (associationMetaData === undefined)
+                    continue;
+                if (targetAssociationType && associationMetaData.type !== targetAssociationType)
+                    continue;
+                const dreamClassOrClasses = associationMetaData.modelCB();
+                if (!dreamClassOrClasses)
+                    throw new FailedToIdentifyAssociation(model, associationMetaData.type, associationName, associationMetaData.globalAssociationNameOrNames);
+                const optional = associationMetaData.type === 'BelongsTo' ? associationMetaData.optional === true : null;
+                const where = associationMetaData.type === 'HasMany' || associationMetaData.type === 'HasOne'
+                    ? associationMetaData.and || null
+                    : null;
+                // NOTE
+                // this try-catch is here because the ASTSchemaBuilder currently needs to be run twice to generate foreignKey
+                // correctly. The first time will raise, since calling Dream.columns is dependant on the schema const to
+                // introspect columns during a foreign key check. This will be repaired once kysely types have been successfully
+                // split off into a separate file from the types we diliver in types/dream.ts
+                let foreignKey = null;
+                try {
+                    const isThroughAssociation = associationMetaData.through;
+                    if (!isThroughAssociation) {
+                        const _foreignKey = associationMetaData.foreignKey();
+                        foreignKey = _foreignKey;
+                    }
+                }
+                catch (err) {
+                    this.hasForeignKeyError = true;
+                }
+                try {
+                    tableAssociationData[associationName] ||= {
+                        tables: [],
+                        type: associationMetaData.type,
+                        polymorphic: associationMetaData.polymorphic,
+                        foreignKey,
+                        foreignKeyTypeColumn: associationMetaData.polymorphic
+                            ? associationMetaData?.foreignKeyTypeField?.() || null
+                            : null,
+                        optional,
+                        and: where,
+                    };
+                    if (foreignKey)
+                        tableAssociationData[associationName]['foreignKey'] = foreignKey;
+                    if (Array.isArray(dreamClassOrClasses)) {
+                        const tables = dreamClassOrClasses.map(dreamClass => dreamClass.table);
+                        tableAssociationData[associationName].tables = [
+                            ...tableAssociationData[associationName].tables,
+                            ...tables,
+                        ];
+                    }
+                    else {
+                        tableAssociationData[associationName].tables.push(dreamClassOrClasses.table);
+                    }
+                    // guarantee unique
+                    tableAssociationData[associationName].tables = [
+                        ...new Set(tableAssociationData[associationName].tables),
+                    ];
+                }
+                catch (error) {
+                    if (!(error instanceof ExplicitForeignKeyRequired || error instanceof InvalidComputedForeignKey))
+                        throw error;
+                }
+            }
+        }
+        return Object.keys(tableAssociationData)
+            .sort()
+            .reduce((acc, key) => {
+            if (tableAssociationData[key] === undefined)
+                return acc;
+            acc[key] = tableAssociationData[key];
+            return acc;
+        }, {});
+    }
+    /**
+     * @internal
+     *
+     * retrieves the table data for an individual table.
+     * Can be used to build up types
+     */
+    async tableData(tableName) {
+        const dreamApp = DreamApp.getOrFail();
+        const models = Object.values(dreamApp.models).filter(model => model.table === tableName);
+        const maybeModel = models[0];
+        if (!maybeModel)
+            throw new Error(`
+Could not find a Dream model with table "${tableName}".
+
+If you recently changed the name of a table in a migration, you
+may need to update the table getter in the corresponding Dream.
+`);
+        const baseModel = maybeModel['stiBaseClassOrOwnClass'];
+        const associationData = this.getAssociationData(tableName);
+        const allStiChildren = models.filter(model => model['isSTIChild']);
+        const modelsToCheck = allStiChildren.length ? allStiChildren : [baseModel];
+        // If a table is STI, then we look only at the serializers attached to
+        // all STI children (not the STI base model because the base model may not have any serializers)
+        const eachModelSerializerKeys = modelsToCheck.map(model => {
+            let serializers = {};
+            try {
+                serializers = model?.prototype?.['serializers'] || {};
+            }
+            catch {
+                // no-op
+            }
+            return Object.keys(serializers);
+        });
+        const serializerKeys = intersection(...eachModelSerializerKeys).sort();
+        return {
+            scopes: {
+                default: uniq(models.flatMap(model => model['scopes'].default.map(scopeStatement => scopeStatement.method))),
+                named: uniq(models.flatMap(model => model['scopes'].named.map(scopeStatement => scopeStatement.method))),
+            },
+            columns: await this.getColumnData(tableName, associationData),
+            virtualColumns: uniq(models.flatMap(model => model['virtualAttributes'].map(prop => prop.property) || [])),
+            associations: associationData,
+            serializerKeys,
+        };
+    }
+    /**
+     * @internal
+     *
+     * retrieves the column data for an individual table and association.
+     * Can be used to build up types
+     */
+    async getColumnData(tableName, allTableAssociationData) {
+        const dbDriverClass = Query.dbDriverClass(this.connectionName);
+        return await dbDriverClass.getColumnData(this.connectionName, tableName, allTableAssociationData);
+    }
+}

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

@@ -0,0 +1,57 @@
+import ts from 'typescript';
+import { CliFileWriter } from '../../cli/CliFileWriter.js';
+import ASTBuilder from './ASTBuilder.js';
+import autogeneratedFileDisclaimer from './autoGeneratedFileDisclaimer.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 ASTGlobalSchemaBuilder extends ASTBuilder {
+    async build() {
+        // build a new, blank source file to populate with our output
+        const sourceFile = ts.createSourceFile('', '', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+        const output = await this.prettier(this.printStatements([this.buildGlobalTypeConfigConst()], sourceFile));
+        await CliFileWriter.write(this.globalSchemaPath(), output);
+    }
+    /**
+     * @internal
+     *
+     * builds up the `export const globalTypeConfig = ...` statement within the dream.globals.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.
+     */
+    buildGlobalTypeConfigConst() {
+        const globalTypeConfigObjectLiteral = f.createObjectLiteralExpression([
+            f.createPropertyAssignment(f.createIdentifier('serializers'), f.createArrayLiteralExpression(this.globalSerializerNames()
+                .sort()
+                .map(key => f.createStringLiteral(key)))),
+        ], true // multiline
+        );
+        // 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 globalTypeConfigObjectLiteralConst = f.createVariableStatement([f.createModifier(ts.SyntaxKind.ExportKeyword)], f.createVariableDeclarationList([
+            f.createVariableDeclaration(f.createIdentifier('globalTypeConfig'), undefined, undefined, constAssertion),
+        ], ts.NodeFlags.Const));
+        return globalTypeConfigObjectLiteralConst;
+    }
+    /**
+     * @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);
+        return `\
+${autogeneratedFileDisclaimer()}
+${result}`;
+    }
+}

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

@@ -0,0 +1,236 @@
+import ts from 'typescript';
+import { CliFileWriter } from '../../cli/CliFileWriter.js';
+import camelize from '../camelize.js';
+import ASTConnectionBuilder from './ASTConnectionBuilder.js';
+import autogeneratedFileDisclaimer from './autoGeneratedFileDisclaimer.js';
+const f = ts.factory;
+/**
+ * Responsible for enhancing the kysely-codegen output, which can be found at
+ * types/db.ts. If you are leveraging multiple db connections,
+ * then this file will also be responsible for building all variants,
+ * i.e. types/db.alternateConnection.ts, etc...
+ *
+ * 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 ASTKyselyCodegenEnhancer extends ASTConnectionBuilder {
+    /**
+     * enhances the kysely codegen output for the given connection name
+     * by reading the relevant db.ts file into AST nodes, then enhancing them
+     * with a variety of transformations necessary to lock this file in with
+     * our other schema files, allowing types to flow correctly throughout the app.
+     */
+    async enhance() {
+        let dbSourceFile = await this.getDbSourceFile();
+        dbSourceFile = this.camelizeKeys(dbSourceFile);
+        dbSourceFile = this.replaceTimestampExport(dbSourceFile);
+        dbSourceFile = this.addMissingImports(dbSourceFile);
+        dbSourceFile = this.replaceInt8Export(dbSourceFile);
+        dbSourceFile = this.sortExportedInterfacesTransformer(dbSourceFile);
+        dbSourceFile = await this.addEnumValueExports(dbSourceFile);
+        dbSourceFile = this.addDeprecatedDbClassExportForBackwardsCompatibility(dbSourceFile);
+        const output = this.printOutput(dbSourceFile);
+        const finalOutput = await this.prettier(`\
+${autogeneratedFileDisclaimer()}
+${output}`);
+        await CliFileWriter.write(this.dbPath(), finalOutput);
+    }
+    addDeprecatedDbClassExportForBackwardsCompatibility(dbSourceFile) {
+        const transformer = () => {
+            return sourceFile => {
+                const dbInterface = this.findDbExport(sourceFile, 'DB');
+                if (!dbInterface)
+                    return sourceFile;
+                const classDec = ts.factory.createClassDeclaration([ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)], ts.factory.createIdentifier('DBClass'), undefined, [], dbInterface.members.filter(ts.isPropertySignature).map(propertySignature => {
+                    return f.createPropertyDeclaration([], propertySignature.name, undefined, propertySignature.type, undefined);
+                }));
+                return ts.factory.updateSourceFile(sourceFile, [...sourceFile.statements, classDec], sourceFile.isDeclarationFile, sourceFile.referencedFiles, sourceFile.typeReferenceDirectives, undefined);
+            };
+        };
+        const result = ts.transform(dbSourceFile, [transformer]);
+        return result.transformed[0];
+    }
+    /**
+     * @internal
+     *
+     * returns the output of the provided dbSourceFile, ensuring that all exports
+     * have a new line above them.
+     */
+    printOutput(dbSourceFile) {
+        const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+        const output = printer.printNode(ts.EmitHint.SourceFile, dbSourceFile, dbSourceFile);
+        return output.replace(/export /g, '\nexport ');
+    }
+    /**
+     * @internal
+     *
+     * ensures that the `Timestamp` exported from db.ts points correctly to either
+     * the DateTime or CalendarDate class, depending on the db type.
+     */
+    replaceTimestampExport(dbSourceFile) {
+        const transformer = context => {
+            return rootNode => {
+                const visit = (node) => {
+                    const typeAlias = this.exportedTypeAliasOrNull(node, 'Timestamp');
+                    if (typeAlias) {
+                        const updatedNode = f.updateTypeAliasDeclaration(typeAlias, typeAlias.modifiers, typeAlias.name, typeAlias.typeParameters, f.createTypeReferenceNode('ColumnType', [
+                            f.createUnionTypeNode([
+                                f.createTypeReferenceNode(f.createIdentifier('DateTime')),
+                                f.createTypeReferenceNode(f.createIdentifier('CalendarDate')),
+                            ]),
+                        ]));
+                        return updatedNode;
+                    }
+                    return ts.visitEachChild(node, visit, context);
+                };
+                return ts.visitNode(rootNode, visit);
+            };
+        };
+        const result = ts.transform(dbSourceFile, [transformer]);
+        return result.transformed[0];
+    }
+    /**
+     * @internal
+     *
+     * massages the `Int8` exported from db.ts to make it more flexible
+     */
+    replaceInt8Export(dbSourceFile) {
+        const transformer = context => {
+            return rootNode => {
+                const visit = (node) => {
+                    const typeAlias = this.exportedTypeAliasOrNull(node, 'Int8');
+                    if (typeAlias) {
+                        return f.updateTypeAliasDeclaration(typeAlias, typeAlias.modifiers, typeAlias.name, typeAlias.typeParameters, f.createTypeReferenceNode('ColumnType', [
+                            f.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+                            f.createUnionTypeNode([
+                                f.createKeywordTypeNode(ts.SyntaxKind.BigIntKeyword),
+                                f.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword),
+                                f.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+                            ]),
+                            f.createUnionTypeNode([
+                                f.createKeywordTypeNode(ts.SyntaxKind.BigIntKeyword),
+                                f.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword),
+                                f.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+                            ]),
+                        ]));
+                    }
+                    return ts.visitEachChild(node, visit, context);
+                };
+                return ts.visitNode(rootNode, visit);
+            };
+        };
+        const result = ts.transform(dbSourceFile, [transformer]);
+        return result.transformed[0];
+    }
+    /**
+     * @internal
+     *
+     * injects missing CalendarDate and DateTime imports from dream
+     */
+    addMissingImports(dbSourceFile) {
+        const transformer = () => {
+            return (sourceFile) => f.updateSourceFile(sourceFile, [...this.dateAndDateTimeImports(), ...sourceFile.statements]);
+        };
+        const result = ts.transform(dbSourceFile, [transformer]);
+        return result.transformed[0];
+    }
+    /**
+     * @internal
+     *
+     * sorts all exported interfaces and puts them above the DB interface
+     */
+    sortExportedInterfacesTransformer(dbSourceFile) {
+        const transformer = () => {
+            return (sourceFile) => {
+                const sortedInterfaceStatements = [];
+                const finalInterfaceStatements = [];
+                const otherStatements = [];
+                sourceFile.statements.forEach(statement => {
+                    if (ts.isInterfaceDeclaration(statement) &&
+                        statement.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword)) {
+                        if (statement.name.text !== 'DB') {
+                            sortedInterfaceStatements.push(statement);
+                        }
+                        else {
+                            finalInterfaceStatements.push(statement);
+                        }
+                    }
+                    else {
+                        otherStatements.push(statement);
+                    }
+                });
+                sortedInterfaceStatements.sort((a, b) => a.name.text.localeCompare(b.name.text));
+                return f.updateSourceFile(sourceFile, [...otherStatements, ...sortedInterfaceStatements, ...finalInterfaceStatements], sourceFile.isDeclarationFile, sourceFile.referencedFiles);
+            };
+        };
+        const result = ts.transform(dbSourceFile, [transformer]);
+        return result.transformed[0];
+    }
+    /**
+     * @internal
+     *
+     * camelizes the keys on all interfaces except the DB interface
+     * (since the DB interface is indexed by table name, which must not be camelized)
+     */
+    camelizeKeys(dbSourceFile) {
+        // @ts-expect-error cannot lock this type down, though implementation is correct
+        const transformer = context => {
+            const visit = node => {
+                const interfaceNode = this.exportedInterfaceOrNull(node);
+                if (interfaceNode &&
+                    !['DB'].includes(interfaceNode.name.text) // Check exclusion list
+                ) {
+                    const updatedMembers = interfaceNode.members.map(member => {
+                        if (ts.isPropertySignature(member) && ts.isIdentifier(member.name)) {
+                            const camelizedKey = camelize(member.name.text);
+                            if (member.name.text !== camelizedKey) {
+                                return f.updatePropertySignature(member, member.modifiers, f.createIdentifier(camelizedKey), member.questionToken, member.type);
+                            }
+                        }
+                        return member;
+                    });
+                    return f.updateInterfaceDeclaration(interfaceNode, interfaceNode.modifiers, interfaceNode.name, interfaceNode.typeParameters, interfaceNode.heritageClauses, updatedMembers);
+                }
+                return ts.visitEachChild(node, visit, context);
+            };
+            return node => ts.visitNode(node, visit);
+        };
+        const result = ts.transform(dbSourceFile, [transformer]);
+        return result.transformed[0];
+    }
+    /**
+     * @internal
+     *
+     * for each found enum in the app (i.e. LocalizedTextsEnum), this will also
+     * inject below it a `LocalizedTextsEnumValues` const, which can be used
+     * at runtime to grab the actual enum values.
+     */
+    async addEnumValueExports(dbSourceFile) {
+        const enums = await this.getAllEnumValueNames();
+        const enumTypes = enums.map(e => e.enumType);
+        // @ts-expect-error cannot lock this type down, though implementation is correct
+        const transformer = context => {
+            const visit = (node) => {
+                const typeAlias = this.exportedTypeAliasOrNull(node);
+                const isEnum = typeAlias ? enumTypes.includes(typeAlias.name.text) : false;
+                if (typeAlias && isEnum) {
+                    const literals = this.extractStringLiteralTypeNodesFromTypeOrUnion(typeAlias).map(node => node.literal.text);
+                    if (literals.length > 0) {
+                        return [
+                            typeAlias,
+                            f.createVariableStatement([f.createModifier(ts.SyntaxKind.ExportKeyword)], f.createVariableDeclarationList([
+                                f.createVariableDeclaration(f.createIdentifier(`${typeAlias.name.text}Values`), undefined, undefined, f.createAsExpression(f.createArrayLiteralExpression(literals.map(literal => f.createStringLiteral(literal)), true // multiLine
+                                ), f.createKeywordTypeNode(ts.SyntaxKind.ConstKeyword))),
+                            ], ts.NodeFlags.Const)),
+                        ];
+                    }
+                }
+                return ts.visitEachChild(node, visit, context);
+            };
+            return node => ts.visitNode(node, visit);
+        };
+        const result = ts.transform(dbSourceFile, [transformer]);
+        return result.transformed[0];
+    }
+}