@rvoh/dream 2.0.4 → 2.1.0

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -1,7 +1,7 @@
 import { DeleteQueryBuilder, Kysely, Transaction as KyselyTransaction, OrderByItemBuilder, SelectQueryBuilder, UpdateQueryBuilder } from 'kysely';
 import { DialectProviderCb } from '../../db/DreamDbConnection.js';
 import Dream from '../../Dream.js';
-import { SchemaBuilderInformationSchemaRow } from '../../helpers/cli/SchemaBuilder.js';
+import { SchemaBuilderInformationSchemaRow } from '../../helpers/cli/ASTBuilder.js';
 import { AssociationStatement } from '../../types/associations/shared.js';
 import { DbConnectionType } from '../../types/db.js';
 import { DreamColumnNames, DreamTableSchema, OrderDir, PrimaryKeyType, SqlCommandType } from '../../types/dream.js';
@@ -37,19 +37,7 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
     /**
      * defines the syncing behavior for dream and psychic,
      * which is run whenever the `sync` command is called.
-     * This is an important step, and will be incredibly
-     * comlpex to override. You will need to do the following
-     * when overriding this method:
-     *
-     * 1. introspect the db and use it to generate a db.ts file in the
-     *    same shape as the existing one. Currently, the process for generating
-     *    this file is extremely complex and messy, and will be difficult
-     *    to achieve.
-     * 2. generate a types/dream.ts file in the same shape as the existing
-     *    one. This is normally done using `await new SchemaBuilder().build()`,
-     *    but this will likely need to be overridden to tailor to your custom
-     *    database engine.
-     */
+     * */
     static sync(connectionName: string, onSync: () => Promise<void> | void, options?: {
         schemaOnly?: boolean;
     }): Promise<void>;

package/dist/types/src/dream/QueryDriver/Postgres.d.ts

@@ -1,5 +1,5 @@
 import Dream from '../../Dream.js';
-import { SchemaBuilderAssociationData, SchemaBuilderColumnData } from '../../helpers/cli/SchemaBuilder.js';
+import { SchemaBuilderAssociationData, SchemaBuilderColumnData } from '../../helpers/cli/ASTBuilder.js';
 import KyselyQueryDriver from './Kysely.js';
 export default class PostgresQueryDriver<DreamInstance extends Dream> extends KyselyQueryDriver<DreamInstance> {
     /**
@@ -27,7 +27,7 @@ export default class PostgresQueryDriver<DreamInstance extends Dream> extends Ky
      * this is used by the SchemaBuilder to store column data permanently
      * within the types/dream.ts file.
      */
-    static getColumnData(connectionName: string, tableName: string, associationData: {
+    static getColumnData(connectionName: string, tableName: string, allTableAssociationData: {
         [key: string]: SchemaBuilderAssociationData;
     }): Promise<{
         [key: string]: SchemaBuilderColumnData;

package/dist/types/src/dream-app/index.d.ts

@@ -4,6 +4,7 @@ import Dream from '../Dream.js';
 import { primaryKeyTypes } from '../dream/constants.js';
 import QueryDriverBase from '../dream/QueryDriver/Base.js';
 import { EncryptOptions } from '../encrypt/index.js';
+import autogeneratedFileDisclaimer from '../helpers/cli/autoGeneratedFileDisclaimer.js';
 import globalClassNameFromFullyQualifiedModelName from '../helpers/globalClassNameFromFullyQualifiedModelName.js';
 import absoluteDreamPath from '../helpers/path/absoluteDreamPath.js';
 import dreamPath from '../helpers/path/dreamPath.js';
@@ -64,6 +65,7 @@ export default class DreamApp {
         inferSerializersFromDreamClassOrViewModelClass: typeof inferSerializersFromDreamClassOrViewModelClass;
         isDreamSerializer: typeof isDreamSerializer;
         serializerNameFromFullyQualifiedModelName: typeof serializerNameFromFullyQualifiedModelName;
+        autogeneratedFileDisclaimer: typeof autogeneratedFileDisclaimer;
     };
     /**
      * @internal
@@ -131,6 +133,14 @@ export default class DreamApp {
     get packageManager(): "yarn" | "npm" | "pnpm";
     private _importExtension;
     get importExtension(): ".js" | ".ts" | "none";
+    /**
+     * 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.
+     */
+    private _bypassDeprecationChecks;
+    get bypassDeprecationChecks(): boolean;
     protected loadedModels: boolean;
     constructor(opts?: Partial<DreamAppOpts>);
     get models(): Record<string, typeof Dream>;
@@ -143,7 +153,7 @@ export default class DreamApp {
     get parallelDatabasesEnabled(): boolean;
     load<RT extends 'models' | 'serializers'>(resourceType: RT, resourcePath: string, importCb: (path: string) => Promise<any>): Promise<void>;
     plugin(cb: (app: DreamApp) => void | Promise<void>): void;
-    set<ApplyOpt extends DreamAppSetOption>(applyOption: ApplyOpt, options: ApplyOpt extends 'db' ? DreamDbCredentialOptions | string : ApplyOpt extends 'encryption' ? DreamAppEncryptionOptions : ApplyOpt extends 'primaryKeyType' ? (typeof primaryKeyTypes)[number] : ApplyOpt extends 'importExtension' ? GeneratorImportStyle : ApplyOpt extends 'logger' ? DreamLogger : ApplyOpt extends 'projectRoot' ? string : ApplyOpt extends 'inflections' ? () => void | Promise<void> : ApplyOpt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : ApplyOpt extends 'paths' ? DreamDirectoryPaths : ApplyOpt extends 'parallelTests' ? number : ApplyOpt extends 'unicodeNormalization' ? UnicodeNormalizationForm : ApplyOpt extends 'paginationPageSize' ? number : never, secondaryOptions?: ApplyOpt extends 'db' ? DreamDbCredentialOptions : never): void;
+    set<ApplyOpt extends DreamAppSetOption>(applyOption: ApplyOpt, options: ApplyOpt extends 'bypassDeprecationChecks' ? boolean : ApplyOpt extends 'db' ? DreamDbCredentialOptions | string : ApplyOpt extends 'encryption' ? DreamAppEncryptionOptions : ApplyOpt extends 'primaryKeyType' ? (typeof primaryKeyTypes)[number] : ApplyOpt extends 'importExtension' ? GeneratorImportStyle : ApplyOpt extends 'logger' ? DreamLogger : ApplyOpt extends 'projectRoot' ? string : ApplyOpt extends 'inflections' ? () => void | Promise<void> : ApplyOpt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : ApplyOpt extends 'paths' ? DreamDirectoryPaths : ApplyOpt extends 'parallelTests' ? number : ApplyOpt extends 'unicodeNormalization' ? UnicodeNormalizationForm : ApplyOpt extends 'paginationPageSize' ? number : never, secondaryOptions?: ApplyOpt extends 'db' ? DreamDbCredentialOptions : never): void;
     on<T extends DreamHookEventType>(hookEventType: T, cb: T extends 'db:log' ? (event: KyselyLogEvent) => void : T extends 'repl:start' ? (context: Context) => void | Promise<void> : never): void;
 }
 export type DreamHookEventType = 'db:log' | 'repl:start';
@@ -156,7 +166,7 @@ export interface DreamAppOpts {
     serializerCasing?: DreamSerializerCasing;
     parallelTests: number | undefined;
 }
-export type DreamAppSetOption = 'db' | 'encryption' | 'inflections' | 'importExtension' | 'logger' | 'paths' | 'primaryKeyType' | 'projectRoot' | 'serializerCasing' | 'parallelTests' | 'unicodeNormalization' | 'paginationPageSize' | 'packageManager';
+export type DreamAppSetOption = 'bypassDeprecationChecks' | 'db' | 'encryption' | 'inflections' | 'importExtension' | 'logger' | 'paths' | 'primaryKeyType' | 'projectRoot' | 'serializerCasing' | 'parallelTests' | 'unicodeNormalization' | 'paginationPageSize' | 'packageManager';
 export interface DreamDirectoryPaths {
     models?: string;
     serializers?: string;

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

@@ -0,0 +1,159 @@
+import ts from 'typescript';
+import { DreamConst } from '../../dream/constants.js';
+/**
+ * @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
+     *
+     * extracts the exportName from the provided dbSourceFile
+     */
+    protected findDbExport(dbSourceFile: ts.SourceFile, exportName: string): ts.Node | undefined;
+    /**
+     * @internal
+     *
+     * returns the path to the dream.globals.ts file
+     */
+    protected globalSchemaPath(): 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;
+    /**
+     * @internal
+     *
+     * returns the DateTime and CalendarDate imports. This is fairly
+     * tricky, since it considers whether or not we are in the dream
+     * internals (i.e. when testing dream). If we are, it will return
+     * valid internal import paths to those files. Otherwise, it will
+     * import them both from @rvoh/dream.
+     */
+    protected dateAndDateTimeImports(): ts.ImportDeclaration[];
+    /**
+     * @internal
+     *
+     * for a given table name (i.e. balloon_lines), it will return the exported
+     * `BalloonLines` interface within the dbSourceFile
+     */
+    protected getTableInterfaceDeclaration(dbSourceFile: ts.SourceFile, tableName: string): ts.InterfaceDeclaration;
+    /**
+     * @internal
+     *
+     * returns an array of global names for all serializers in the app
+     */
+    protected globalSerializerNames(): string[];
+}
+export interface SchemaData {
+    [key: string]: TableData;
+}
+export interface TableData {
+    serializerKeys: readonly string[];
+    scopes: {
+        default: readonly string[];
+        named: readonly string[];
+    };
+    columns: Readonly<{
+        [key: string]: SchemaBuilderColumnData;
+    }>;
+    virtualColumns: readonly string[];
+    associations: Readonly<{
+        [key: string]: SchemaBuilderAssociationData;
+    }>;
+}
+export interface SchemaBuilderAssociationData {
+    tables: string[];
+    type: 'BelongsTo' | 'HasOne' | 'HasMany';
+    polymorphic: boolean;
+    optional: boolean | null;
+    foreignKey: string | null;
+    foreignKeyTypeColumn: string | null;
+    and: Record<string, string | typeof DreamConst.passthrough | typeof DreamConst.required> | null;
+}
+export interface SchemaBuilderColumnData {
+    dbType: string;
+    allowNull: boolean;
+    enumType: string | null;
+    enumValues: string | null;
+    foreignKey: string | null;
+    isArray: boolean;
+}
+export interface SchemaBuilderInformationSchemaRow {
+    columnName: string;
+    udtName: string;
+    dataType: string;
+    isNullable: 'YES' | 'NO';
+}

package/dist/types/src/helpers/cli/ASTConnectionBuilder.d.ts

@@ -0,0 +1,104 @@
+import ts from 'typescript';
+import ASTBuilder, { SchemaData } 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 {
+    protected connectionName: string;
+    hasForeignKeyError: boolean;
+    constructor(connectionName: string);
+    /**
+     * @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
+     */
+    protected schemaPath(): string;
+    /**
+     * @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
+     */
+    protected dbPath(): string;
+    /**
+     * @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.
+     */
+    protected getDbSourceFile(): Promise<ts.SourceFile>;
+    /**
+     * @internal
+     *
+     * reads the db source file for the given connection, returning the contents
+     * as a raw string
+     */
+    protected loadDbSyncFile(): Promise<string>;
+    /**
+     * @internal
+     *
+     * builds up the schema data for every table into an object, which
+     * can be read and injected into AST nodes.
+     */
+    protected getSchemaData(): Promise<SchemaData>;
+    /**
+     * @internal
+     *
+     * used by getSchemaData to build up all table data
+     */
+    private getTables;
+    /**
+     * @internal
+     *
+     * finds all enums used by the app, and returns information
+     * about those enums that can be used for type generating purpposes
+     */
+    protected getAllEnumValueNames(): Promise<{
+        enumValues: string;
+        enumType: string;
+    }[]>;
+    /**
+     * @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.
+     */
+    protected globalModelNames(): [string, string][];
+    /**
+     * @internal
+     *
+     * retrieves useful association data for a given association and table, which
+     * can be used to build up types
+     */
+    private getAssociationData;
+    /**
+     * @internal
+     *
+     * retrieves the table data for an individual table.
+     * Can be used to build up types
+     */
+    private tableData;
+    /**
+     * @internal
+     *
+     * retrieves the column data for an individual table and association.
+     * Can be used to build up types
+     */
+    private getColumnData;
+}

package/dist/types/src/helpers/cli/ASTGlobalSchemaBuilder.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 ASTGlobalSchemaBuilder extends ASTBuilder {
+    build(): Promise<void>;
+    /**
+     * @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.
+     */
+    private buildGlobalTypeConfigConst;
+    /**
+     * @internal
+     *
+     * writes the compiled statements to string.
+     *
+     */
+    private printStatements;
+}

package/dist/types/src/helpers/cli/ASTKyselyCodegenEnhancer.d.ts

@@ -0,0 +1,68 @@
+import ASTConnectionBuilder from './ASTConnectionBuilder.js';
+/**
+ * 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.
+     */
+    enhance(): Promise<void>;
+    private addDeprecatedDbClassExportForBackwardsCompatibility;
+    /**
+     * @internal
+     *
+     * returns the output of the provided dbSourceFile, ensuring that all exports
+     * have a new line above them.
+     */
+    private printOutput;
+    /**
+     * @internal
+     *
+     * ensures that the `Timestamp` exported from db.ts points correctly to either
+     * the DateTime or CalendarDate class, depending on the db type.
+     */
+    private replaceTimestampExport;
+    /**
+     * @internal
+     *
+     * massages the `Int8` exported from db.ts to make it more flexible
+     */
+    private replaceInt8Export;
+    /**
+     * @internal
+     *
+     * injects missing CalendarDate and DateTime imports from dream
+     */
+    private addMissingImports;
+    /**
+     * @internal
+     *
+     * sorts all exported interfaces and puts them above the DB interface
+     */
+    private sortExportedInterfacesTransformer;
+    /**
+     * @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)
+     */
+    private camelizeKeys;
+    /**
+     * @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.
+     */
+    private addEnumValueExports;
+}

package/dist/types/src/helpers/cli/ASTSchemaBuilder.d.ts

@@ -0,0 +1,80 @@
+import ASTConnectionBuilder from './ASTConnectionBuilder.js';
+/**
+ * Responsible for building dream schema, which can be found at
+ * types/dream.ts. If you are leveraging multiple db connections,
+ * then this file will also be responsible for building all variants,
+ * i.e. types/dream.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 ASTSchemaBuilder extends ASTConnectionBuilder {
+    /**
+     * builds the new contents for the dream schema file (i.e. types/dream.ts
+     * for default connection), and writes it to the file. This is automatically
+     * done anytime the sync cli command is called, which happens when migrating,
+     * rolling back, and when manually calling the sync command via CLI.
+     */
+    build(): Promise<void>;
+    /**
+     * @internal
+     *
+     * builds up the `export const schema = ...` statement within the dream.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 buildSchemaConst;
+    /**
+     * @internal
+     *
+     * builds up the `export const connectionTypeConfig = ...` statement within the dream.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 buildConnectionTypeConfigConst;
+    /**
+     * @internal
+     *
+     * writes the compiled statements to string. Will also manually inject new lines
+     * into the import statements, since otherwise, they are forced into a single line
+     * and are completely unreadable that way.
+     *
+     * prettier is used in a later step to optimize output, but the user may not have
+     * prettier installed, in which case it will do nothing, and we don't want to leave
+     * the imports unformatted in those cases.
+     */
+    private printStatements;
+    /**
+     * @internal
+     *
+     * builds up an AST statement representing the DB imports that the dream.ts
+     * file will need in order to render without import errors. It takes the aggregated
+     * list of imported types and imported variables built up as the schema was being
+     * built, and uses them to build AST import nodes, which can be rendered into the
+     * schema source file.
+     */
+    private dbImports;
+    /**
+     * @internal
+     *
+     * given a column and table, this method returns the coerced type representation
+     * of whatever type was found in the db.ts file. In most cases, it will simply
+     * return the same type as was found, but in some cases it will perform coercion
+     * to provide consistent and useful types to the underlying application.
+     *
+     * Amongst other things, it will convert Numeric -> number, Int8 -> string, etc...
+     * Timestamp will be carefully converted to either CalendarDate or DateTime, depending
+     * on if the type set in the db is a date or datetime field.
+     */
+    private getCoercedTypeForTableColumn;
+    /**
+     * @internal
+     *
+     * used by the getCoercedTypeForTableColumn to get the specific type for a column
+     * if no coercion is necessary, the original type node will be returned
+     */
+    private coercedType;
+}

package/dist/types/src/helpers/cli/DBClassDeprecation.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 DBClassDeprecation {
+    deprecate(): Promise<void>;
+}