Class Entity<TSchema, TRels, TVariantUnion, TReadVariants>

constructor

• new Entity<
      TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>,
      TRels extends
          Record<
              string,
              RelationInfo<any, ObjectSchemaBuilder<any, any, any, any, any, any, any>>,
          > = {},
      TVariantUnion = never,
      TReadVariants extends ReadVariants = {},
  >(
      schema: TSchema,
  ): Entity<TSchema, TRels, TVariantUnion, TReadVariants>

  Wrap a schema as an entity definition with typed relation metadata. Prefer defineEntity(schema) for inference. Relation/variant methods return new definitions; constructing an Entity does not query or create database tables.

  Type Parameters

  • TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>
  • TRels extends Record<
        string,
        RelationInfo<any, ObjectSchemaBuilder<any, any, any, any, any, any, any>>,
    > = {}
  • TVariantUnion = never
  • TReadVariants extends ReadVariants = {}

  Parameters

  • schema: TSchema

  Returns Entity<TSchema, TRels, TVariantUnion, TReadVariants>

Readonlyschema

belongsTo

• belongsTo<
      TKey extends string,
      TForeign extends
          ObjectSchemaBuilder<any, any, any, any, any, any, any> = UnwrapNavSchema<
          SchemaProps<TSchema>[TKey],
      >,
      TOptional extends boolean = false,
  >(
      navSel: EntityPropSelector<TSchema, TKey>,
      localSel: EntityPropSelector<TSchema>,
      _remoteSel: EntityPropSelector<TForeign>,
      opts?: { optional?: TOptional },
  ): Entity<
      TSchema,
      TRels & {
          -readonly [P in string]-?: RelationInfo<"belongsTo", TForeign> & {
              optional: TOptional;
          }
      },
      TVariantUnion,
      TReadVariants,
  >

  Declare a many-to-one relation where the FK lives on THIS table.

  Type Parameters

  • TKey extends string
  • TForeign extends ObjectSchemaBuilder<any, any, any, any, any, any, any> = UnwrapNavSchema<SchemaProps<TSchema>[TKey]>
  • TOptional extends boolean = false

  Parameters

  • navSel: EntityPropSelector<TSchema, TKey>

    Selector of nav property (foreign schema, usually .optional()).

  • localSel: EntityPropSelector<TSchema>

    Selector of local-side FK property: l => l.userId

  • _remoteSel: EntityPropSelector<TForeign>

    Selector of foreign-side PK property: r => r.id

  • Optionalopts: { optional?: TOptional }

  Returns Entity<
      TSchema,
      TRels & {
          -readonly [P in string]-?: RelationInfo<"belongsTo", TForeign> & {
              optional: TOptional;
          }
      },
      TVariantUnion,
      TReadVariants,
  >

belongsToMany

• belongsToMany<
      TKey extends string,
      TForeign extends
          ObjectSchemaBuilder<any, any, any, any, any, any, any> = UnwrapNavSchema<
          SchemaProps<TSchema>[TKey],
      >,
  >(
      navSel: EntityPropSelector<TSchema, TKey>,
      through: { foreignKey: string; localKey: string; table: string },
  ): WithRelation<
      TSchema,
      TRels,
      TKey,
      "belongsToMany",
      TForeign,
      TVariantUnion,
      TReadVariants,
  >

  Declare a many-to-many relation through a pivot table.

  Type Parameters

  • TKey extends string
  • TForeign extends ObjectSchemaBuilder<any, any, any, any, any, any, any> = UnwrapNavSchema<SchemaProps<TSchema>[TKey]>

  Parameters

  • navSel: EntityPropSelector<TSchema, TKey>

    Selector of nav array property: t => t.tags

  • through: { foreignKey: string; localKey: string; table: string }

    Pivot table config { table, localKey, foreignKey }.

  Returns WithRelation<
      TSchema,
      TRels,
      TKey,
      "belongsToMany",
      TForeign,
      TVariantUnion,
      TReadVariants,
  >

ctiVariant

• ctiVariant<
      TVarSchema extends
          ObjectSchemaBuilder<any, any, any, any, any, any, any>,
      const TKey extends string,
      TForeignKey extends string,
      TVarRelations extends
          Record<
              string,
              RelationInfo<any, ObjectSchemaBuilder<any, any, any, any, any, any, any>>,
          >,
      TAllowOrphan extends boolean = false,
  >(
      key: TKey,
      variant: Entity<TVarSchema, TVarRelations>,
      fkSel: EntityPropSelector<TVarSchema, TForeignKey>,
      opts?: {
          allowOrphan?: TAllowOrphan;
          relations?: Record<string, VariantRelationInput<TVarSchema>>;
      },
  ): Entity<
      TSchema,
      TRels,
      TVariantUnion
      | VariantBranch<TSchema, TVarSchema>,
      WithReadVariant<
          TReadVariants,
          TKey,
          {
              allowOrphan: TAllowOrphan;
              foreignKey: TForeignKey;
              schema: EntityReadSchema<TVarSchema, TVarRelations>;
              storage: "cti";
          },
      >,
  >

  Declare a CTI (Class Table Inheritance) variant. Only valid after .discriminator(). Returns a new Entity whose schema carries the updated 'variants' extension.

  Type Parameters

  • TVarSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>
  • const TKey extends string
  • TForeignKey extends string
  • TVarRelations extends Record<
        string,
        RelationInfo<any, ObjectSchemaBuilder<any, any, any, any, any, any, any>>,
    >
  • TAllowOrphan extends boolean = false

  Parameters

  • key: TKey

    Discriminator literal (e.g. 'image').

  • variant: Entity<TVarSchema, TVarRelations>

    Entity wrapping the variant table schema.

  • fkSel: EntityPropSelector<TVarSchema, TForeignKey>

    Accessor returning the FK property on the variant schema that joins back to the base PK.

  • Optionalopts: {
        allowOrphan?: TAllowOrphan;
        relations?: Record<string, VariantRelationInput<TVarSchema>>;
    }

    { allowOrphan?: boolean; relations?: ... } — see CTI docs.

  Returns Entity<
      TSchema,
      TRels,
      TVariantUnion
      | VariantBranch<TSchema, TVarSchema>,
      WithReadVariant<
          TReadVariants,
          TKey,
          {
              allowOrphan: TAllowOrphan;
              foreignKey: TForeignKey;
              schema: EntityReadSchema<TVarSchema, TVarRelations>;
              storage: "cti";
          },
      >,
  >

discriminator

• discriminator<TKey extends string>(
      sel: TKey | EntityPropSelector<TSchema, TKey>,
  ): Entity<TSchema, TRels, never, { discriminator: TKey; variants: {} }>

  Mark this entity as polymorphic by selecting the discriminator property. Returns a new Entity whose .ctiVariant() / .stiVariant() methods declare each variant.

  Declare ordinary relations (.belongsTo() etc.) on this entity BEFORE .discriminator(). After .discriminator() you are in the polymorphic-builder phase: .hasOne/.hasMany/.belongsTo/.belongsToMany still work, but the per-variant relations live on the .ctiVariant() / .stiVariant() calls.

  Type Parameters

  • TKey extends string

  Parameters

  • sel: TKey | EntityPropSelector<TSchema, TKey>

  Returns Entity<TSchema, TRels, never, { discriminator: TKey; variants: {} }>

  Example

  const FileEntity = defineEntity(FileSchema)
      .discriminator(t => t.type)
      .ctiVariant('image',    ImageEntity,    t => t.fileId)
      .ctiVariant('document', DocumentEntity, t => t.fileId);
  Copy

hasMany

• hasMany<
      TKey extends string,
      TForeign extends
          ObjectSchemaBuilder<any, any, any, any, any, any, any> = UnwrapNavSchema<
          SchemaProps<TSchema>[TKey],
      >,
  >(
      navSel: EntityPropSelector<TSchema, TKey>,
      _localSel: EntityPropSelector<TSchema>,
      remoteSel: EntityPropSelector<TForeign>,
  ): WithRelation<
      TSchema,
      TRels,
      TKey,
      "hasMany",
      TForeign,
      TVariantUnion,
      TReadVariants,
  >

  Declare a one-to-many relation where the FK lives on the FOREIGN table.

  Type Parameters

  • TKey extends string
  • TForeign extends ObjectSchemaBuilder<any, any, any, any, any, any, any> = UnwrapNavSchema<SchemaProps<TSchema>[TKey]>

  Parameters

  • navSel: EntityPropSelector<TSchema, TKey>

    Selector of nav array property: t => t.posts

  • _localSel: EntityPropSelector<TSchema>

    Selector of local-side join key: l => l.id

  • remoteSel: EntityPropSelector<TForeign>

    Selector of remote-side FK on foreign schema: r => r.userId

  Returns WithRelation<
      TSchema,
      TRels,
      TKey,
      "hasMany",
      TForeign,
      TVariantUnion,
      TReadVariants,
  >

hasOne

• hasOne<
      TKey extends string,
      TForeign extends
          ObjectSchemaBuilder<any, any, any, any, any, any, any> = UnwrapNavSchema<
          SchemaProps<TSchema>[TKey],
      >,
  >(
      navSel: EntityPropSelector<TSchema, TKey>,
      _localSel: EntityPropSelector<TSchema>,
      remoteSel: EntityPropSelector<TForeign>,
      opts?: { optional?: boolean },
  ): WithRelation<
      TSchema,
      TRels,
      TKey,
      "hasOne",
      TForeign,
      TVariantUnion,
      TReadVariants,
  >

  Declare a one-to-one relation where the FK lives on the FOREIGN table. navSel selects the navigation property on THIS schema (must hold the foreign schema, typically .optional()). The foreign schema is auto-resolved at runtime from that property; provided explicitly here via opts.foreign only when peeling fails.

  Type Parameters

  • TKey extends string
  • TForeign extends ObjectSchemaBuilder<any, any, any, any, any, any, any> = UnwrapNavSchema<SchemaProps<TSchema>[TKey]>

  Parameters

  • navSel: EntityPropSelector<TSchema, TKey>

    Selector of nav property: t => t.author

  • _localSel: EntityPropSelector<TSchema>

    Selector of local-side join key: l => l.id

  • remoteSel: EntityPropSelector<TForeign>

    Selector of remote-side FK on foreign schema: r => r.userId

  • Optionalopts: { optional?: boolean }

    Optional { optional?: boolean } (default false).

  Returns WithRelation<
      TSchema,
      TRels,
      TKey,
      "hasOne",
      TForeign,
      TVariantUnion,
      TReadVariants,
  >

stiVariant

• stiVariant<
      TVarSchema extends
          ObjectSchemaBuilder<any, any, any, any, any, any, any>,
      const TKey extends string,
      TVarRelations extends
          Record<
              string,
              RelationInfo<any, ObjectSchemaBuilder<any, any, any, any, any, any, any>>,
          > = {},
  >(
      key: TKey,
      body: TVarSchema | Entity<TVarSchema, TVarRelations, never, {}>,
      opts?: {
          enforceCheck?: boolean;
          relations?: Record<string, VariantRelationInput<TVarSchema>>;
      },
  ): Entity<
      TSchema,
      TRels,
      TVariantUnion
      | VariantBranch<TSchema, TVarSchema>,
      WithReadVariant<
          TReadVariants,
          TKey,
          { schema: EntityReadSchema<TVarSchema, TVarRelations>; storage: "sti" },
      >,
  >

  Declare an STI (Single Table Inheritance) variant. Only valid after .discriminator(). Accepts either an Entity or a bare ObjectSchemaBuilder.

  Type Parameters

  • TVarSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>
  • const TKey extends string
  • TVarRelations extends Record<
        string,
        RelationInfo<any, ObjectSchemaBuilder<any, any, any, any, any, any, any>>,
    > = {}

  Parameters

  • key: TKey
  • body: TVarSchema | Entity<TVarSchema, TVarRelations, never, {}>
  • Optionalopts: {
        enforceCheck?: boolean;
        relations?: Record<string, VariantRelationInput<TVarSchema>>;
    }

  Returns Entity<
      TSchema,
      TRels,
      TVariantUnion
      | VariantBranch<TSchema, TVarSchema>,
      WithReadVariant<
          TReadVariants,
          TKey,
          { schema: EntityReadSchema<TVarSchema, TVarRelations>; storage: "sti" },
      >,
  >