joist-codegen 2.3.0 → 2.4.0-next.2

package/build/EntityDbMetadata.d.mts

@@ -0,0 +1,301 @@
+import { Config } from "./config.mjs";
+import { Action, Column, M2MRelation, M2ORelation, O2MRelation, Table } from "./pgMetadata.mjs";
+import { EnumMetadata, EnumRow, PgEnumMetadata } from "./loadMetadata.mjs";
+import { Code, Import } from "ts-poet";
+//#region src/EntityDbMetadata.d.ts
+/** All the entities + enums in our database. */
+interface DbMetadata {
+  entities: EntityDbMetadata[];
+  /** Type name i.e. `Author` to metadata. */
+  entitiesByName: Record<string, EntityDbMetadata>;
+  enums: EnumMetadata;
+  pgEnums: PgEnumMetadata;
+  joinTables: string[];
+  /** Other non-joist tables in the schema. */
+  otherTables: string[];
+  totalTables: number;
+}
+/** Codegen-time metadata about a given domain entity. */
+type Entity = {
+  name: string;
+  /** The _type_ symbol pointing to the entity itself. */
+  type: Import;
+  /** The symbol pointing to the entity itself. */
+  typeSymbol: Import;
+  /** The symbol pointing to the entity itself, directly rather than via entities.ts */
+  typeForMetadataFile: Import;
+  /** The name of the entity's runtime metadata const. */
+  metaName: string;
+  /** The symbol pointing to the entity's runtime metadata const. */
+  metaType: Import;
+  /** The symbol pointing to the entity's EntityId type. */
+  idType: Import;
+  /** The symbol pointing to the entity's Order type. */
+  orderType: Import;
+  /** The symbol pointing to the entity's config const. */
+  configConst: Import;
+  optsType: Import;
+  /** i.e. `AuthorId` (or `Author_Id` on conflict). */
+  idName: string;
+  /** i.e. `AuthorFields`. */
+  fieldsName: string;
+  /** i.e. `AuthorOpts`. */
+  optsName: string;
+  /** i.e. `AuthorIdsOpts`. */
+  idsOptsName: string;
+  /** i.e. `AuthorFilter`. */
+  filterName: string;
+  /** i.e. `AuthorGraphQLFilter`. */
+  graphqlFilterName: string;
+  /** i.e. `AuthorOrder`. */
+  orderName: string;
+  /** i.e. `AuthorFactoryExtras`. */
+  factoryExtrasName: string;
+  /** i.e. `AuthorScope`. */
+  scopeName: string;
+  /** i.e. `AuthorScopes`. */
+  scopesName: string;
+};
+type DatabaseColumnType = "boolean" | "int" | "uuid" | "numeric" | "smallint" | "integer" | "bigint" | "decimal" | "real" | "smallserial" | "serial" | "bigserial" | "double precision" | "text" | "citext" | "character varying" | "varchar" | "time without time zone" | "timestamp with time zone" | "timestamp without time zone" | "date" | "jsonb" | "bytea" | "tsvector" | "tstzrange";
+/**
+ * A logical entity field.
+ *
+ * I.e. it may be a physical db column, or multiple physical db columns, or a "virtual" field like
+ * the one-to-many collection side of a many-to-one foreign key. */
+interface Field {
+  fieldName: string;
+  ignore?: boolean;
+}
+type PrimitiveTypescriptType = "boolean" | "string" | "number" | "Object" | "bigint" | "Uint8Array" | Code;
+type PrimitiveField = Field & {
+  kind: "primitive";
+  columnName: string;
+  /** Physical table owner, unchanged by domain inheritance specialization. */
+  columnOwner: Entity;
+  columnType: DatabaseColumnType;
+  columnDefault: number | boolean | string | null;
+  columnGenerated: boolean;
+  /** Database nullability, unchanged by domain inheritance specialization. */
+  columnNotNull: boolean;
+  fieldType: PrimitiveTypescriptType | Import;
+  rawFieldType: PrimitiveTypescriptType;
+  notNull: boolean;
+  derived: "orm" | "sync" | "async" | false;
+  protected: boolean;
+  unique: boolean;
+  superstruct: Import | undefined;
+  zodSchema: Import | undefined;
+  customSerde: Import | undefined;
+  isArray: boolean;
+  hasConfigDefault: boolean;
+  lazy?: boolean;
+};
+type EnumField = Field & {
+  kind: "enum";
+  columnName: string;
+  /** Physical table owner, unchanged by domain inheritance specialization. */
+  columnOwner: Entity;
+  columnType: DatabaseColumnType;
+  columnDefault: number | boolean | string | null;
+  columnGenerated: boolean;
+  columnNotNull: boolean;
+  derived: "sync" | "async" | false;
+  enumName: string;
+  enumType: Import;
+  enumDetailType: Import;
+  enumDetailsType: Import;
+  enumRows: EnumRow[];
+  notNull: boolean;
+  isArray: boolean;
+  hasConfigDefault: boolean;
+};
+type PgEnumField = Field & {
+  kind: "pg-enum";
+  columnName: string;
+  /** Physical table owner, unchanged by domain inheritance specialization. */
+  columnOwner: Entity;
+  columnDefault: number | boolean | string | null;
+  columnGenerated: boolean;
+  columnNotNull: boolean;
+  /** I.e. `favorite_shape`. */
+  dbType: string;
+  /** I.e. `FavoriteShape`. */
+  enumName: string;
+  enumType: Import;
+  enumValues: string[];
+  notNull: boolean;
+  hasConfigDefault: boolean;
+};
+/** I.e. a `Book.author` reference pointing to an `Author`. */
+type ManyToOneField = Field & {
+  kind: "m2o";
+  columnName: string;
+  /** Physical table owner, unchanged by domain inheritance specialization. */
+  columnOwner: Entity;
+  columnDefault?: number | boolean | string | null;
+  columnGenerated: boolean;
+  columnNotNull: boolean;
+  dbType: string;
+  otherFieldName: string;
+  otherEntity: Entity;
+  notNull: boolean;
+  isDeferredAndDeferrable: boolean;
+  constraintName: string;
+  derived: "async" | false;
+  hasConfigDefault: boolean;
+  onDelete: Action;
+};
+/** I.e. a `Author.books` collection. */
+type OneToManyField = Field & {
+  kind: "o2m";
+  singularName: string;
+  otherEntity: Entity;
+  otherFieldName: string;
+  otherColumnName: string;
+  otherColumnNotNull: boolean;
+  isLargeCollection: boolean;
+  orderBy: {
+    field: string;
+    direction: "ASC" | "DESC";
+  } | undefined;
+  softDeletes: "include" | "exclude" | undefined;
+};
+/** I.e. a `Author.image` reference when `image.author_id` is unique. */
+type OneToOneField = Field & {
+  kind: "o2o";
+  otherEntity: Entity;
+  otherFieldName: string;
+  otherColumnName: string;
+  otherColumnNotNull: boolean;
+};
+type ManyToManyField = Field & {
+  kind: "m2m";
+  joinTableName: string;
+  singularName: string;
+  columnName: string;
+  otherEntity: Entity;
+  otherFieldName: string;
+  otherColumnName: string;
+  isLargeCollection: boolean;
+  isDeferredAndDeferrable: boolean;
+  derived: "async" | "otherSide" | false;
+  softDeletes: "include" | "exclude" | undefined;
+  /** Whether the join table has a surrogate `id` PK; if false the FK pair is the composite PK. */
+  hasJoinTableId: boolean;
+};
+/** I.e. a `Publisher.logoColors` m2m to the `color` enum table, backed by `publisher_logo_colors`. */
+type ManyToManyEnumField = Field & {
+  kind: "m2mEnum";
+  joinTableName: string;
+  /** The entity's FK column, e.g. `publisher_id`. */
+  columnName: string;
+  /** The enum's FK column, e.g. `logo_color_id`. */
+  otherColumnName: string;
+  enumName: string;
+  enumType: Import;
+  enumDetailType: Import;
+  enumDetailsType: Import;
+  enumRows: EnumRow[];
+  /** Whether the join table has a surrogate `id` PK; if false the FK pair is the composite PK. */
+  hasJoinTableId: boolean;
+};
+/** I.e. a `Comment.parent` reference that groups `comments.parent_book_id` and `comments.parent_book_review_id`. */
+type PolymorphicField = Field & {
+  kind: "poly";
+  fieldType: string;
+  notNull: boolean;
+  hasConfigDefault: boolean;
+  components: PolymorphicFieldComponent[];
+};
+/** A column such as `parent_book_id` or `parent_book_review_id`. */
+type PolymorphicFieldComponent = {
+  columnName: string;
+  /** Physical table owner, unchanged by domain inheritance specialization. */
+  columnOwner: Entity;
+  otherFieldName: string;
+  otherEntity: Entity;
+  isDeferredAndDeferrable: boolean;
+  constraintName: string;
+  notNull: false;
+};
+type FieldNameOverrides = {
+  fieldName?: string;
+  otherFieldName?: string;
+};
+/** Adapts PostgreSQL catalog metadata into our specific ORM types. */
+declare class EntityDbMetadata {
+  entity: Entity;
+  primaryKey: PrimitiveField;
+  primitives: PrimitiveField[];
+  enums: EnumField[];
+  pgEnums: PgEnumField[];
+  manyToOnes: ManyToOneField[];
+  oneToManys: OneToManyField[];
+  largeOneToManys: OneToManyField[];
+  oneToOnes: OneToOneField[];
+  manyToManys: ManyToManyField[];
+  largeManyToManys: ManyToManyField[];
+  manyToManyEnums: ManyToManyEnumField[];
+  polymorphics: PolymorphicField[];
+  tableName: string;
+  tagName: string;
+  createdAt: PrimitiveField | undefined;
+  updatedAt: PrimitiveField | undefined;
+  deletedAt: PrimitiveField | undefined;
+  baseClassName: string | undefined;
+  baseType: EntityDbMetadata | undefined;
+  subTypes: EntityDbMetadata[];
+  inheritanceType: "sti" | "cti" | undefined;
+  /** This will only be set on the base meta. */
+  stiDiscriminatorField?: string;
+  /** This will only be set on the sub metas. */
+  stiDiscriminatorValue?: number;
+  abstract: boolean;
+  nonDeferredFkOrder: number;
+  uniqueConstraints?: string[][];
+  /** Gates mutation targets, not reads; false when required columns or array storage have no supported mutation mapping. */
+  supportsEmExecute?: boolean;
+  /** Original table fields, captured before inheritance partitions or specializes them. */
+  physicalMetadata?: EntityDbMetadata;
+  /** Physical columns ignored by entity fields, retained for direct SQL reads and writes. */
+  ignoredColumns: PrimitiveField[];
+  constructor(config: Config, table: Table, enums?: EnumMetadata);
+  get name(): string;
+  get nonDeferredFks(): Array<ManyToOneField | PolymorphicFieldComponent>;
+  get nonDeferredManyToManyFks(): Array<ManyToManyField>;
+}
+/** Finds the field name for o2o side of a o2o/m2o. */
+declare function oneToOneName(config: Config, refEntity: Entity, keyEntity: Entity, r: M2ORelation | O2MRelation): string;
+declare function referenceName(config: Config, entity: Entity, r: M2ORelation | O2MRelation): string;
+declare function manyToManyName(column: Column): string;
+/** Returns the collection name to use on `entity` when referring to `otherEntity`s. */
+declare function collectionName(config: Config, singleEntity: Entity, collectionEntity: Entity, r: M2ORelation | O2MRelation | M2MRelation): {
+  fieldName: string;
+  singularName: string;
+};
+declare function failIfOverlappingFieldNames(entity: EntityDbMetadata): void;
+declare function makeEntity(entityName: string): Entity;
+/**
+ * Collapses the per-relation `otherEntity` copies down to the one primary `Entity` per name.
+ *
+ * `makeEntity` mints a fresh `Entity` for every relation's `otherEntity`, so each entity ends up with
+ * many duplicate objects floating around. Pointing them all at the single `entitiesByName[name].entity`
+ * instance means later passes (i.e. `resolveNameConflicts`) only have to update one object per name.
+ *
+ * Must run after inheritance, since STI/CTI specialization both adds and re-points `otherEntity`s.
+ */
+declare function canonicalizeOtherEntities(db: DbMetadata): void;
+/**
+ * Rewrites codegen'd type names that collide with another exported type name.
+ *
+ * `makeEntity` defaults each name to the conventional `${name}<Suffix>`, but if a separate entity or
+ * enum is literally named e.g. `AuthorScope` or `AuthorOrder`, our generated type of the same name
+ * would collide with it, so we fall back to `Author_Scope` / `Author_Order`.
+ *
+ * Relies on `canonicalizeOtherEntities` having run, so mutating each primary `meta.entity` also updates
+ * the `otherEntity` references that point at it (e.g. `Book.author: AuthorId` follows `Author`'s rename).
+ */
+declare function resolveNameConflicts(config: Config, db: DbMetadata): void;
+//#endregion
+export { DatabaseColumnType, DbMetadata, Entity, EntityDbMetadata, EnumField, FieldNameOverrides, ManyToManyEnumField, ManyToManyField, ManyToOneField, OneToManyField, OneToOneField, PgEnumField, PolymorphicField, PolymorphicFieldComponent, PrimitiveField, PrimitiveTypescriptType, canonicalizeOtherEntities, collectionName, failIfOverlappingFieldNames, makeEntity, manyToManyName, oneToOneName, referenceName, resolveNameConflicts };
+//# sourceMappingURL=EntityDbMetadata.d.mts.map

package/build/EntityDbMetadata.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityDbMetadata.d.mts","names":[],"sources":["../src/EntityDbMetadata.ts"],"mappings":";;;;;;UAmDiB;EACf,UAAU;;EAEV,gBAAgB,eAAe;EAC/B,OAAO;EACP,SAAS;EACT;;EAEA;EACA;;;KAIU;EACV;;EAEA,MAAM;;EAEN,YAAY;;EAEZ,qBAAqB;;EAErB;;EAEA,UAAU;;EAEV,QAAQ;;EAER,WAAW;;EAEX,aAAa;EACb,UAAU;;EAKV;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;KAGU;;;;;;UAgCF;EACR;EACA;;KAGU,iGAAiG;KAEjG,iBAAiB;EAC3B;EACA;;EAEA,aAAa;EACb,YAAY;EACZ;EACA;;EAEA;EAEA,WAAW,0BAA0B;EACrC,cAAc;EACd;EACA;EACA;EACA;EACA,aAAa;EACb,WAAW;EACX,aAAa;EACb;EACA;EACA;;KAGU,YAAY;EACtB;EACA;;EAEA,aAAa;EACb,YAAY;EACZ;EACA;EACA;EACA;EACA;EACA,UAAU;EACV,gBAAgB;EAChB,iBAAiB;EACjB,UAAU;EACV;EACA;EACA;;KAGU,cAAc;EACxB;EACA;;EAEA,aAAa;EACb;EACA;EACA;;EAEA;;EAEA;EACA,UAAU;EACV;EACA;EACA;;;KAIU,iBAAiB;EAC3B;EACA;;EAEA,aAAa;EACb;EACA;EACA;EACA;EACA;EACA,aAAa;EACb;EACA;EACA;EACA;EACA;EACA,UAAU;;;KAIA,iBAAiB;EAC3B;EACA;EACA,aAAa;EACb;EACA;EACA;EACA;EACA;IAAW;IAAe;;EAC1B;;;KAIU,gBAAgB;EAC1B;EACA,aAAa;EACb;EACA;EACA;;KAGU,kBAAkB;EAC5B;EACA;EACA;EACA;EACA,aAAa;EACb;EACA;EACA;EACA;EACA;EACA;;EAEA;;;KAIU,sBAAsB;EAChC;EACA;;EAEA;;EAEA;EACA;EACA,UAAU;EACV,gBAAgB;EAChB,iBAAiB;EACjB,UAAU;;EAEV;;;KAIU,mBAAmB;EAC7B;EACA;EACA;EACA;EACA,YAAY;;;KAIF;EACV;;EAEA,aAAa;EACb;EACA,aAAa;EACb;EACA;EACA;;KAGU;EACV;EACA;;;cAIW;EACX,QAAQ;EACR,YAAY;EACZ,YAAY;EACZ,OAAO;EACP,SAAS;EACT,YAAY;EACZ,YAAY;EACZ,iBAAiB;EACjB,WAAW;EACX,aAAa;EACb,kBAAkB;EAClB,iBAAiB;EACjB,cAAc;EACd;EACA;EACA,WAAW;EACX,WAAW;EACX,WAAW;EACX;EACA,UAAU;EACV,UAAU;EACV;;EAEA;;EAEA;EACA;EACA;EACA;;EAEA;;EAEA,mBAAmB;;EAEnB,gBAAgB;EAEhB,YAAY,QAAQ,QAAQ,OAAO,OAAO,QAAO;MAqI7C;MAIA,kBAAkB,MAAM,iBAAiB;MAOzC,4BAA4B,MAAM;;;iBAqcxB,aACd,QAAQ,QAER,WAAW,QAEX,WAAW,QACX,GAAG,cAAc;iBAgCH,cAAc,QAAQ,QAAQ,QAAQ,QAAQ,GAAG,cAAc;iBAmB/D,eAAe,QAAQ;;iBAUvB,eACd,QAAQ,QAER,cAAc,QAEd,kBAAkB,QAClB,GAAG,cAAc,cAAc;EAC5B;EAAmB;;iBA4BR,4BAA4B,QAAQ;iBAwBpC,WAAW,qBAAqB;;;;;;;;;;iBA6BhC,0BAA0B,IAAI;;;;;;;;;;;iBAgC9B,qBAAqB,QAAQ,QAAQ,IAAI"}