joist-core 2.3.0 → 2.4.0-next.2

package/build/EntityMetadata.js

@@ -1,78 +1,61 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getMetadata = getMetadata;
-exports.getMetadataForField = getMetadataForField;
-exports.isOneToManyField = isOneToManyField;
-exports.isManyToOneField = isManyToOneField;
-exports.isManyToManyField = isManyToManyField;
-exports.isManyToManyEnumField = isManyToManyEnumField;
-exports.isOneToOneField = isOneToOneField;
-exports.isPolymorphicField = isPolymorphicField;
-exports.isReferenceField = isReferenceField;
-exports.isCollectionField = isCollectionField;
-exports.getBaseAndSelfMetas = getBaseAndSelfMetas;
-exports.getBaseSelfAndSubMetas = getBaseSelfAndSubMetas;
-exports.getSubMetas = getSubMetas;
-exports.getBaseMeta = getBaseMeta;
-const BaseEntity_1 = require("./BaseEntity");
-const Entity_1 = require("./Entity");
-const configure_1 = require("./configure");
+import { getMetadataForType } from "./configure.js";
+import "./config.js";
+import "./EntityManager.js";
+import { isEntity } from "./Entity.js";
+import { getInstanceData } from "./BaseEntity.js";
+//#region src/EntityMetadata.ts
 function getMetadata(param) {
-    if (!param)
-        throw new Error(`Cannot getMetadata of ${param}`);
-    return (typeof param === "function" ? param.metadata : "cstr" in param ? param : (0, BaseEntity_1.getInstanceData)(param).metadata);
+	if (!param) throw new Error(`Cannot getMetadata of ${param}`);
+	return typeof param === "function" ? param.metadata : "cstr" in param ? param : getInstanceData(param).metadata;
 }
 /** Returns the metadata layer that declares `fieldName`, i.e. `Task.tags` for `TaskOld.tags`. */
 function getMetadataForField(meta, fieldName) {
-    if (!meta.allFields[fieldName])
-        throw new Error(`Field '${fieldName}' not found on ${meta.type}`);
-    // I.e. `TaskOld.tags` is an STI-inherited `Task.tags` and should walk up, but `SmallPublisherGroup.publishers`
-    // is a CTI-specialized `PublisherGroup.publishers` and should stay on `SmallPublisherGroup`.
-    while (!(fieldName in meta.fields) && meta.allFields[fieldName]?.specialized !== true && meta.baseType) {
-        meta = (0, configure_1.getMetadataForType)(meta.baseType);
-    }
-    return meta;
+	if (!meta.allFields[fieldName]) throw new Error(`Field '${fieldName}' not found on ${meta.type}`);
+	while (!(fieldName in meta.fields) && meta.allFields[fieldName]?.specialized !== true && meta.baseType) meta = getMetadataForType(meta.baseType);
+	return meta;
 }
 function isOneToManyField(ormField) {
-    return ormField.kind === "o2m";
+	return ormField.kind === "o2m";
 }
 function isManyToOneField(ormField) {
-    return ormField.kind === "m2o";
+	return ormField.kind === "m2o";
 }
 function isManyToManyField(ormField) {
-    return ormField.kind === "m2m";
+	return ormField.kind === "m2m";
 }
 function isManyToManyEnumField(ormField) {
-    return ormField.kind === "m2mEnum";
+	return ormField.kind === "m2mEnum";
 }
 function isOneToOneField(ormField) {
-    return ormField.kind === "o2o";
+	return ormField.kind === "o2o";
 }
 function isPolymorphicField(ormField) {
-    return ormField.kind === "poly";
+	return ormField.kind === "poly";
 }
 function isReferenceField(ormField) {
-    return ormField.kind === "m2o" || ormField.kind === "o2o" || ormField.kind === "poly";
+	return ormField.kind === "m2o" || ormField.kind === "o2o" || ormField.kind === "poly";
 }
 function isCollectionField(ormField) {
-    return ormField.kind === "o2m" || ormField.kind === "m2m";
+	return ormField.kind === "o2m" || ormField.kind === "m2m";
 }
 function getBaseAndSelfMetas(param) {
-    return (0, Entity_1.isEntity)(param) ? getBaseSelfAndSubMetas(getMetadata(param)) : [...param.baseTypes, param];
+	return isEntity(param) ? getBaseSelfAndSubMetas(getMetadata(param)) : param.baseSelfMetas ?? [...param.baseTypes, param];
 }
 function getBaseSelfAndSubMetas(meta) {
-    return [...meta.baseTypes, meta, ...meta.subTypes];
+	return meta.baseSelfAndSubMetas ?? [
+		...meta.baseTypes,
+		meta,
+		...meta.subTypes
+	];
 }
 function getSubMetas(meta) {
-    // We should do recursion at some point
-    return meta.subTypes;
+	return meta.subTypes;
 }
 function getBaseMeta(meta) {
-    if (!meta.baseType) {
-        return meta;
-    }
-    else {
-        return meta.baseTypes[0];
-    }
+	if (!meta.baseType) return meta;
+	else return meta.baseTypes[0];
 }
+//#endregion
+export { getBaseAndSelfMetas, getBaseMeta, getBaseSelfAndSubMetas, getMetadata, getMetadataForField, getSubMetas, isCollectionField, isManyToManyEnumField, isManyToManyField, isManyToOneField, isOneToManyField, isOneToOneField, isPolymorphicField, isReferenceField };
+
 //# sourceMappingURL=EntityMetadata.js.map

package/build/EntityMetadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"EntityMetadata.js","sourceRoot":"","sources":["../src/EntityMetadata.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EntityMetadata.js","names":[],"sources":["../src/EntityMetadata.ts"],"sourcesContent":["import { getInstanceData } from \"src/BaseEntity.ts\";\nimport { type ConfigApi, type Reactable, type ReactiveRule } from \"src/config.ts\";\nimport { getMetadataForType } from \"src/configure.ts\";\nimport { type Entity, isEntity } from \"src/Entity.ts\";\nimport { type EntityManager, type MaybeAbstractEntityConstructor, type TimestampFields } from \"src/EntityManager.ts\";\nimport { type EnumMetadata } from \"src/EnumMetadata.ts\";\nimport type { DeepNew } from \"src/loading/loadHints.ts\";\nimport type { Column, ColumnDescriptors } from \"src/serde/columns.ts\";\nimport type { FieldSerde, PolymorphicKeySerde } from \"src/serde/fieldSerde.ts\";\n\nexport function getMetadata<T extends Entity>(entity: T): EntityMetadata<T>;\nexport function getMetadata<T extends Entity>(type: MaybeAbstractEntityConstructor<T>): EntityMetadata<T>;\nexport function getMetadata<T extends Entity>(meta: EntityMetadata): EntityMetadata;\nexport function getMetadata<T extends Entity>(\n  param: T | MaybeAbstractEntityConstructor<T> | EntityMetadata,\n): EntityMetadata {\n  if (!param) throw new Error(`Cannot getMetadata of ${param}`);\n  return (\n    typeof param === \"function\" ? (param as any).metadata : \"cstr\" in param ? param : getInstanceData(param).metadata\n  ) as EntityMetadata;\n}\n\n/** Returns the metadata layer that declares `fieldName`, i.e. `Task.tags` for `TaskOld.tags`. */\nexport function getMetadataForField(meta: EntityMetadata, fieldName: string): EntityMetadata {\n  if (!meta.allFields[fieldName]) throw new Error(`Field '${fieldName}' not found on ${meta.type}`);\n  // I.e. `TaskOld.tags` is an STI-inherited `Task.tags` and should walk up, but `SmallPublisherGroup.publishers`\n  // is a CTI-specialized `PublisherGroup.publishers` and should stay on `SmallPublisherGroup`.\n  while (!(fieldName in meta.fields) && meta.allFields[fieldName]?.specialized !== true && meta.baseType) {\n    meta = getMetadataForType(meta.baseType);\n  }\n  return meta;\n}\n\n/**\n * Runtime metadata about an entity.\n *\n * The `joist-codegen` step will generate this by reading the database schema at build/codegen\n * time, along with any customizations in `joist-config.json`.\n *\n * Note: This has no generic, like `T extends Entity`, because `Entity<IdType>` i.e. with\n * an unknown string/id type, causes issues when we want to generically mix `EntityMetadata`\n * of different types, that even liberally using `EntityMetadata<any>` did not avoid.\n */\nexport interface EntityMetadata<T extends Entity = any> {\n  cstr: MaybeAbstractEntityConstructor<T>;\n  type: string;\n  /** How the domain entity's id is represented. */\n  idType: \"tagged-string\" | \"untagged-string\" | \"number\";\n  /** The database column type, i.e. used to do `::type` casts in Postgres. */\n  idDbType: \"bigint\" | \"int\" | \"uuid\" | \"text\";\n  tableName: string;\n  /** Whether codegen verified this table is a supported SQL mutation target; does not gate reads. */\n  supportsEmExecute?: boolean;\n  /** If we're a subtype, our immediate base type's name, e.g. for `SmallPublisher` this would be `Publisher`. */\n  baseType: string | undefined;\n  inheritanceType?: \"sti\" | \"cti\" | undefined;\n  /** Indicates the field to use to derive which subtype to instantiate; only set on the base meta. */\n  stiDiscriminatorField?: string;\n  /** The discriminator enum value for this subtype; only set on sub metas. */\n  stiDiscriminatorValue?: number;\n  /** Whether this type is abstract (cannot be instantiated directly). */\n  ctiAbstract?: boolean;\n  tagName: string;\n  fields: Record<string, Field>;\n  /** Physical storage descriptors, without CTI base columns; STI metadata shares its base table. */\n  columns: ColumnDescriptors;\n  allFields: Record<string, Field & { aliasSuffix: string; specialized?: true }>;\n  /** Usually polys are in `allFields`, but we pull the components out for comp-specific finds, like `parentBook`. */\n  polyComponentFields?: Record<string, Field & { aliasSuffix: string }>;\n  // Using `any` to avoid type errors between BaseType.metadata & SubType.metadata static fields\n  config: ConfigApi<any, any>;\n  /** The lazy list of non-read-only reactables for this metadata and its base types. */\n  reactables?: Reactable[];\n  /** The lazy lookup of non-read-only reactables by source field name. */\n  reactablesByField?: ReadonlyMap<string, Reactable[]>;\n  /** The lazy list of all reactables for this metadata and its base types. */\n  reactablesIncludingReadOnly?: Reactable[];\n  /** The lazy lookup of all reactables by source field name. */\n  reactablesIncludingReadOnlyByField?: ReadonlyMap<string, Reactable[]>;\n  /** The lazy list of reactive validation rules for this metadata and its subtypes. */\n  reactiveRules?: ReactiveRule[];\n  /** The lazy list of reactive *commit* rules (post-flush/pre-commit) for this metadata and its subtypes. */\n  reactiveCommitRules?: ReactiveRule[];\n  /** Lazily-cached: whether flushing an entity of this type could trigger any `addCommitRule` work. */\n  hasCommitRules?: boolean;\n  /** The lazily-cached set of own `lazy` primitive field names, i.e. columns excluded from the default SELECT. */\n  lazyFieldNames?: ReadonlySet<string>;\n  /** The lazily-cached list of sync-derived (`hasReactiveField`-less) field names, recalced during flush. */\n  syncDerivedFields?: string[];\n  /** Lazily-cached: whether this entity has any `lazy` columns, i.e. so the default SELECT lists columns explicitly. */\n  hasLazyColumns?: boolean;\n  orderBy: string | undefined;\n  /** Flat field names that can be used to find existing rows before creating. I.e. [[\"email\"], [\"author\", \"title\"]]. */\n  uniqueBy?: string[][];\n  timestampFields: TimestampFields | undefined;\n  // Ideally this would be the application-specific EntityManager (to avoid anys), but it doesn't really matter\n  factory: (em: EntityManager<any, any, any>, opts?: any) => DeepNew<T>;\n  /** The list of base types for this subtype, e.g. for Dog it'd be [Animal, Mammal]. */\n  baseTypes: EntityMetadata[];\n  /** The list of subtypes for this base type, e.g. for Animal it'd be `[Mammal, Dog]`. */\n  subTypes: EntityMetadata[];\n  /** Cached `[...baseTypes, this]` set up by `configureMetadata`, so hot paths avoid re-allocating it. */\n  baseSelfMetas?: EntityMetadata[];\n  /** Cached `[...baseTypes, this, ...subTypes]` set up by `configureMetadata`, so hot paths avoid re-allocating it. */\n  baseSelfAndSubMetas?: EntityMetadata[];\n  /** The lazy lookup of subtypes by type name, i.e. `Animal.metadata.subTypesByType.get(\"Dog\")`. */\n  subTypesByType?: ReadonlyMap<string, EntityMetadata>;\n  /** The lazy lookup of STI subtypes by discriminator value, i.e. `Task.metadata.subTypesByStiValue.get(1)`. */\n  subTypesByStiValue?: ReadonlyMap<unknown, EntityMetadata>;\n  /** The lazy STI discriminator column name, i.e. `Task.metadata.stiDiscriminatorColumnName`. */\n  stiDiscriminatorColumnName?: string;\n  /** If the schema is lacking deferred FKs, this is our insertion order. */\n  nonDeferredFkOrder?: number;\n}\n\nexport type Field =\n  | PrimaryKeyField\n  | PrimitiveField\n  | EnumField\n  | OneToManyField\n  | LargeOneToManyField\n  | ManyToOneField\n  | ManyToManyField\n  | ManyToManyEnumField\n  | OneToOneField\n  | PolymorphicField;\n\n// Only the fields that have defined `serde` keys; should be a mapped type of Field\nexport type SerdeField = PrimaryKeyField | PrimitiveField | EnumField | ManyToOneField | PolymorphicField;\n\nexport type PrimaryKeyField = {\n  kind: \"primaryKey\";\n  fieldName: string;\n  fieldIdName: undefined;\n  required: true;\n  serde: FieldSerde;\n  immutable: true;\n};\n\nexport type PrimitiveField = {\n  kind: \"primitive\";\n  fieldName: string;\n  fieldIdName: undefined;\n  required: boolean;\n  derived: \"orm\" | \"sync\" | \"async\" | false;\n  protected: boolean;\n  type: string | Function;\n  serde: FieldSerde;\n  immutable: boolean;\n  citext?: boolean;\n  default?: \"schema\" | \"config\";\n  sanitize?: boolean;\n  /** When true, this column is excluded from the entity's default SELECT and lazy-loaded via a `LazyField`. */\n  lazy?: boolean;\n};\n\nexport type EnumField = {\n  kind: \"enum\";\n  fieldName: string;\n  fieldIdName: undefined;\n  required: boolean;\n  derived: \"sync\" | \"async\" | false;\n  enumDetailType: { getValues(): ReadonlyArray<unknown>; findById(id: any): unknown };\n  serde: FieldSerde;\n  immutable: boolean;\n  default?: \"schema\" | \"config\";\n};\n\nexport type OneToManyField = {\n  kind: \"o2m\";\n  fieldName: string;\n  fieldIdName: string;\n  required: boolean;\n  otherMetadata: () => EntityMetadata;\n  otherFieldName: string;\n  /** Useful when our other side is a poly, to find which component points back to us. */\n  otherColumnName: string;\n  serde: undefined;\n  immutable: false;\n  orderBy?: { field: string; direction: \"ASC\" | \"DESC\" };\n  /** When `\"include\"`, this collection's `.get`/`.load` returns soft-deleted entities instead of hiding them. */\n  softDeletes?: \"include\" | \"exclude\";\n};\n\nexport type LargeOneToManyField = {\n  kind: \"lo2m\";\n  fieldName: string;\n  fieldIdName: string;\n  required: boolean;\n  otherMetadata: () => EntityMetadata;\n  otherFieldName: string;\n  /** Useful when our other side is a poly, to find which component points back to us. */\n  otherColumnName: string;\n  serde: undefined;\n  immutable: false;\n};\n\nexport type ManyToOneField = {\n  kind: \"m2o\";\n  fieldName: string;\n  fieldIdName: string;\n  required: boolean;\n  otherMetadata: () => EntityMetadata;\n  otherFieldName: string;\n  serde: FieldSerde;\n  immutable: boolean;\n  derived: \"async\" | false;\n  default?: \"schema\" | \"config\";\n};\n\nexport type ManyToManyField = {\n  kind: \"m2m\";\n  fieldName: string;\n  fieldIdName: string;\n  required: boolean;\n  derived: \"async\" | \"otherSide\" | false;\n  otherMetadata: () => EntityMetadata;\n  otherFieldName: string;\n  serde: undefined;\n  immutable: false;\n  joinTableName: string;\n  columnNames: [string, string];\n  /** Whether the join table has a surrogate `id` PK; if false the FK pair is the composite PK. */\n  hasJoinTableId: boolean;\n  /** When `\"include\"`, this collection's `.get`/`.load` returns soft-deleted entities instead of hiding them. */\n  softDeletes?: \"include\" | \"exclude\";\n};\n\n/**\n * A many-to-many between an entity and an enum \"table\", e.g. `Publisher.logoColors` backed by a\n * `publisher_logo_colors` join table joining `publishers` to the `color` enum table.\n *\n * To the user this looks like an array of enum codes (`Color[]`), but unlike an enum-array column it\n * is lazy (needs a load hint) because it lives in its own join table.\n */\nexport type ManyToManyEnumField = {\n  kind: \"m2mEnum\";\n  fieldName: string;\n  fieldIdName: undefined;\n  required: false;\n  derived: false;\n  /** The enum's metadata, used to map enum codes <-> their numeric ids. */\n  enumDetailType: EnumMetadata<any, any, number>;\n  serde: undefined;\n  immutable: false;\n  joinTableName: string;\n  /** `[entityColumn, enumColumn]`, e.g. `[\"publisher_id\", \"color_id\"]`. */\n  columnNames: [string, string];\n  /** Whether the join table has a surrogate `id` PK; if false the FK pair is the composite PK. */\n  hasJoinTableId: boolean;\n};\n\nexport type OneToOneField = {\n  kind: \"o2o\";\n  fieldName: string;\n  fieldIdName: string;\n  required: boolean;\n  otherMetadata: () => EntityMetadata;\n  otherFieldName: string;\n  /** Useful when our other side is a poly, to find which component points back to us. */\n  otherColumnName: string;\n  serde: undefined;\n  immutable: false;\n};\n\nexport type PolymorphicField = {\n  kind: \"poly\";\n  fieldName: string; // eg `parent`\n  fieldIdName: string; // `parentId`\n  required: boolean;\n  components: PolymorphicFieldComponent[];\n  serde: PolymorphicKeySerde;\n  immutable: boolean;\n};\n\nexport type PolymorphicFieldComponent = {\n  otherMetadata: () => EntityMetadata;\n  otherFieldName: string; // eg `comment` or `comments`\n  columnName: string; // eg `parent_book_id` or `parent_book_review_id`\n  column: Column;\n};\n\nexport function isOneToManyField(ormField: Field): ormField is OneToManyField {\n  return ormField.kind === \"o2m\";\n}\n\nexport function isManyToOneField(ormField: Field): ormField is ManyToOneField {\n  return ormField.kind === \"m2o\";\n}\n\nexport function isManyToManyField(ormField: Field): ormField is ManyToManyField {\n  return ormField.kind === \"m2m\";\n}\n\nexport function isManyToManyEnumField(ormField: Field): ormField is ManyToManyEnumField {\n  return ormField.kind === \"m2mEnum\";\n}\n\nexport function isOneToOneField(ormField: Field): ormField is OneToOneField {\n  return ormField.kind === \"o2o\";\n}\n\nexport function isPolymorphicField(ormField: Field): ormField is PolymorphicField {\n  return ormField.kind === \"poly\";\n}\n\nexport function isReferenceField(ormField: Field): ormField is ManyToOneField | OneToOneField | PolymorphicField {\n  return ormField.kind === \"m2o\" || ormField.kind === \"o2o\" || ormField.kind === \"poly\";\n}\n\nexport function isCollectionField(ormField: Field): ormField is OneToManyField | ManyToManyField {\n  return ormField.kind === \"o2m\" || ormField.kind === \"m2m\";\n}\n\nexport function getBaseAndSelfMetas(meta: EntityMetadata): EntityMetadata[];\nexport function getBaseAndSelfMetas(entity: Entity): EntityMetadata[];\nexport function getBaseAndSelfMetas(param: Entity | EntityMetadata): EntityMetadata[] {\n  return isEntity(param)\n    ? getBaseSelfAndSubMetas(getMetadata(param))\n    : (param.baseSelfMetas ?? [...param.baseTypes, param]);\n}\n\nexport function getBaseSelfAndSubMetas(meta: EntityMetadata): EntityMetadata[] {\n  return meta.baseSelfAndSubMetas ?? [...meta.baseTypes, meta, ...meta.subTypes];\n}\n\nexport function getSubMetas(meta: EntityMetadata): EntityMetadata[] {\n  // We should do recursion at some point\n  return meta.subTypes;\n}\n\nexport function getBaseMeta(meta: EntityMetadata): EntityMetadata {\n  if (!meta.baseType) {\n    return meta;\n  } else {\n    return meta.baseTypes[0];\n  }\n}\n"],"mappings":";;;;;;AAaA,SAAgB,YACd,OACgB;CAChB,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,yBAAyB,OAAO;CAC5D,OACE,OAAO,UAAU,aAAc,MAAc,WAAW,UAAU,QAAQ,QAAQ,gBAAgB,KAAK,CAAC,CAAC;AAE7G;;AAGA,SAAgB,oBAAoB,MAAsB,WAAmC;CAC3F,IAAI,CAAC,KAAK,UAAU,YAAY,MAAM,IAAI,MAAM,UAAU,UAAU,iBAAiB,KAAK,MAAM;CAGhG,OAAO,EAAE,aAAa,KAAK,WAAW,KAAK,UAAU,UAAU,EAAE,gBAAgB,QAAQ,KAAK,UAC5F,OAAO,mBAAmB,KAAK,QAAQ;CAEzC,OAAO;AACT;AA2PA,SAAgB,iBAAiB,UAA6C;CAC5E,OAAO,SAAS,SAAS;AAC3B;AAEA,SAAgB,iBAAiB,UAA6C;CAC5E,OAAO,SAAS,SAAS;AAC3B;AAEA,SAAgB,kBAAkB,UAA8C;CAC9E,OAAO,SAAS,SAAS;AAC3B;AAEA,SAAgB,sBAAsB,UAAkD;CACtF,OAAO,SAAS,SAAS;AAC3B;AAEA,SAAgB,gBAAgB,UAA4C;CAC1E,OAAO,SAAS,SAAS;AAC3B;AAEA,SAAgB,mBAAmB,UAA+C;CAChF,OAAO,SAAS,SAAS;AAC3B;AAEA,SAAgB,iBAAiB,UAAgF;CAC/G,OAAO,SAAS,SAAS,SAAS,SAAS,SAAS,SAAS,SAAS,SAAS;AACjF;AAEA,SAAgB,kBAAkB,UAA+D;CAC/F,OAAO,SAAS,SAAS,SAAS,SAAS,SAAS;AACtD;AAIA,SAAgB,oBAAoB,OAAkD;CACpF,OAAO,SAAS,KAAK,IACjB,uBAAuB,YAAY,KAAK,CAAC,IACxC,MAAM,iBAAiB,CAAC,GAAG,MAAM,WAAW,KAAK;AACxD;AAEA,SAAgB,uBAAuB,MAAwC;CAC7E,OAAO,KAAK,uBAAuB;EAAC,GAAG,KAAK;EAAW;EAAM,GAAG,KAAK;CAAQ;AAC/E;AAEA,SAAgB,YAAY,MAAwC;CAElE,OAAO,KAAK;AACd;AAEA,SAAgB,YAAY,MAAsC;CAChE,IAAI,CAAC,KAAK,UACR,OAAO;MAEP,OAAO,KAAK,UAAU;AAE1B"}

package/build/EnumMetadata.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });

package/build/EnumMetadata.d.cts

@@ -0,0 +1,18 @@
+//#region src/EnumMetadata.d.ts
+interface EnumMetadata<C, D, I extends number | string = number | string> {
+  /** Returns the enum type's name, i.e. `AuthorStatus`. */
+  name: string;
+  /** Gets the `code` details, i.e. `Statuses.getByCode(Status.DRAFT)`. */
+  getByCode(code: C): D;
+  /** Finds a code details for `code`, i.e. `Statuses.findByCode("DRAFT")`, returns `undefined` is not found. */
+  findByCode(code: string): D | undefined;
+  /** Finds a code details for `id`, i.e. `Statuss.findById(2)`, returns `undefined` is not found. */
+  findById(id: I): D | undefined;
+  /** Returns all the codes, i.e. `[Status.DRAFT, Status.PUBLISHED]`. */
+  getValues(): ReadonlyArray<C>;
+  /** Returns all the details. */
+  getDetails(): ReadonlyArray<D>;
+}
+//#endregion
+export { EnumMetadata };
+//# sourceMappingURL=EnumMetadata.d.cts.map

package/build/EnumMetadata.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnumMetadata.d.cts","names":[],"sources":["../src/EnumMetadata.ts"],"mappings":";UAAiB,aAAa,GAAG,GAAG;;EAElC;;EAGA,UAAU,MAAM,IAAI;;EAGpB,WAAW,eAAe;;EAG1B,SAAS,IAAI,IAAI;;EAGjB,aAAa,cAAc;;EAG3B,cAAc,cAAc"}

package/build/EnumMetadata.d.mts

@@ -0,0 +1,18 @@
+//#region src/EnumMetadata.d.ts
+interface EnumMetadata<C, D, I extends number | string = number | string> {
+  /** Returns the enum type's name, i.e. `AuthorStatus`. */
+  name: string;
+  /** Gets the `code` details, i.e. `Statuses.getByCode(Status.DRAFT)`. */
+  getByCode(code: C): D;
+  /** Finds a code details for `code`, i.e. `Statuses.findByCode("DRAFT")`, returns `undefined` is not found. */
+  findByCode(code: string): D | undefined;
+  /** Finds a code details for `id`, i.e. `Statuss.findById(2)`, returns `undefined` is not found. */
+  findById(id: I): D | undefined;
+  /** Returns all the codes, i.e. `[Status.DRAFT, Status.PUBLISHED]`. */
+  getValues(): ReadonlyArray<C>;
+  /** Returns all the details. */
+  getDetails(): ReadonlyArray<D>;
+}
+//#endregion
+export { EnumMetadata };
+//# sourceMappingURL=EnumMetadata.d.mts.map

package/build/EnumMetadata.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnumMetadata.d.mts","names":[],"sources":["../src/EnumMetadata.ts"],"mappings":";UAAiB,aAAa,GAAG,GAAG;;EAElC;;EAGA,UAAU,MAAM,IAAI;;EAGpB,WAAW,eAAe;;EAG1B,SAAS,IAAI,IAAI;;EAGjB,aAAa,cAAc;;EAG3B,cAAc,cAAc"}

package/build/EnumMetadata.js

@@ -1,3 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=EnumMetadata.js.map
+export {};

package/build/IndexManager.cjs

@@ -0,0 +1,178 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_relations_Reference = require("./relations/Reference.cjs");
+require("./relations/index.cjs");
+const require_utils = require("./utils.cjs");
+const require_EntityMetadata = require("./EntityMetadata.cjs");
+const require_Entity = require("./Entity.cjs");
+//#region src/IndexManager.ts
+const emptySet = /* @__PURE__ */ new Set();
+const indexThreshold = 500;
+/**
+* IndexManager provides field-based indexing for entity queries to avoid O(n) linear scans of `em.entities`.
+*
+* Key features:
+* - Only indexes entity types with >1000 entities to avoid overhead for small datasets
+* - Supports dual indexing for m2o/poly fields (by ID for saved, by instance for unsaved)
+* - Automatically maintains indexes when fields are updated via setField()
+*/
+var IndexManager = class {
+	#indexes = /* @__PURE__ */ new Map();
+	/** @return if we should index entities of this type/count. */
+	shouldIndexType(entityCount) {
+		return entityCount >= 500;
+	}
+	/** Visible for testing. */
+	isIndexed(tagName) {
+		return this.#indexes.has(tagName);
+	}
+	/** Enables indexing for an entity type and builds indexes for the requested fields. */
+	enableIndexingForType(meta, entities, where) {
+		const { tagName } = meta;
+		if (!this.#indexes.has(tagName)) this.#indexes.set(tagName, /* @__PURE__ */ new Map());
+		const fieldNames = Object.keys(where);
+		const fieldIndexes = this.#indexes.get(tagName);
+		const missingFieldNames = fieldNames.filter((fieldName) => !fieldIndexes.has(fieldName));
+		if (missingFieldNames.length === 0) return;
+		if (meta.baseType || meta.subTypes.length > 0) [...require_utils.groupBy(entities, (e) => require_EntityMetadata.getMetadata(e)).entries()].forEach(([meta, entities]) => {
+			this.addEntitiesToIndex(meta, entities, missingFieldNames);
+		});
+		else this.addEntitiesToIndex(meta, entities, missingFieldNames);
+	}
+	/** Updates indexes when a field value changes. */
+	maybeUpdateFieldIndex(entity, fieldName, oldValue, newValue) {
+		if (this.#indexes.size === 0) return;
+		const meta = require_EntityMetadata.getMetadata(entity);
+		const fieldIndexes = this.#indexes.get(meta.tagName);
+		if (!fieldIndexes) return;
+		const fieldIndex = fieldIndexes.get(fieldName)?.index;
+		if (!fieldIndex) return;
+		fieldIndex.remove(oldValue, entity);
+		fieldIndex.add(newValue, entity);
+	}
+	/**
+	* Finds entities matching the given where clause using indexes.
+	*
+	* Returns the raw candidate set (possibly a live internal index set, so do not mutate it);
+	* the caller applies its own subtype/deleted filtering while building the final array.
+	*/
+	findMatching(meta, entities, where) {
+		const { tagName } = meta;
+		if (!this.#indexes.has(tagName)) throw new Error(`${meta.type} is not indexed`);
+		const fieldIndexes = this.#indexes.get(tagName);
+		let candidates;
+		for (const [fieldName, value] of Object.entries(where)) {
+			this.indexUnindexedEntities(entities, fieldName);
+			const fieldCandidates = fieldIndexes.get(fieldName)?.index.get(value);
+			if (!candidates) candidates = fieldCandidates ?? emptySet;
+			else candidates = fieldCandidates ? intersectSets(candidates, fieldCandidates) : emptySet;
+			if (candidates.size === 0) break;
+		}
+		if (candidates === void 0) throw new Error(`Expected where clause with at least one condition`);
+		return candidates;
+	}
+	addEntitiesToIndex(meta, entities, fieldNames) {
+		const { tagName } = meta;
+		const indexes = this.#indexes.get(tagName);
+		for (const fieldName of fieldNames) {
+			const field = meta.allFields[fieldName];
+			if (!field) continue;
+			let entry = indexes.get(fieldName);
+			if (!entry) {
+				entry = {
+					field,
+					index: new FieldIndex(),
+					indexedCount: 0
+				};
+				indexes.set(fieldName, entry);
+			}
+			for (const entity of entities) {
+				if (entity.isDeletedEntity) continue;
+				const value = getFieldValue(entity, fieldName, entry.field);
+				entry.index.add(value, entity);
+			}
+			entry.indexedCount = entities.length;
+		}
+	}
+	/** Lazily indexes newly-registered entities only for fields that are queried. */
+	indexUnindexedEntities(entities, fieldName) {
+		const first = entities[0];
+		if (first === void 0) return;
+		const meta = require_EntityMetadata.getMetadata(first);
+		const entry = this.#indexes.get(meta.tagName)?.get(fieldName);
+		if (entry === void 0 || entry.indexedCount === entities.length) return;
+		for (let i = entry.indexedCount; i < entities.length; i++) {
+			const entity = entities[i];
+			if (entity.isDeletedEntity) continue;
+			const value = getFieldValue(entity, fieldName, entry.field);
+			entry.index.add(value, entity);
+		}
+		entry.indexedCount = entities.length;
+	}
+};
+function getFieldValue(entity, fieldName, field) {
+	const fn = fieldName;
+	switch (field.kind) {
+		case "primaryKey": return entity.idTaggedMaybe;
+		case "enum":
+		case "primitive": return entity[fn];
+		case "m2o":
+		case "poly":
+			const relation = entity[fn];
+			if (require_relations_Reference.isLoadedReference(relation)) return relation.get;
+			else if (relation.isSet) return relation.id;
+			else return;
+		default: return;
+	}
+}
+/**
+* For a given field, like `firstName`, holds the reverse index of value `bob` -> entities `[a1, a2]`.
+*
+* This also handles indexes `Entity` values as both instances & IDs, to handle both:
+* - new/unpersisted entities not yet having IDs, and
+* - relations not having loaded their instances yet
+*/
+var FieldIndex = class {
+	#valueToEntities = /* @__PURE__ */ new Map();
+	/** @return entities that have `value` as their current value for this field. */
+	get(value) {
+		if (require_Entity.isEntity(value) && value.idTaggedMaybe) {
+			const matchId = this.#valueToEntities.get(value.idTaggedMaybe);
+			const matchInstance = this.#valueToEntities.get(value);
+			if (matchId && matchInstance) return /* @__PURE__ */ new Set([...matchId, ...matchInstance]);
+			return matchId ?? matchInstance;
+		}
+		if (value === null) value = void 0;
+		return this.#valueToEntities.get(value);
+	}
+	add(value, entity) {
+		if (require_Entity.isEntity(value) && value.idTaggedMaybe) this.doAdd(value.idTaggedMaybe, entity);
+		this.doAdd(value, entity);
+	}
+	remove(value, entity) {
+		if (require_Entity.isEntity(value) && value.idTaggedMaybe) this.doRemove(value.idTaggedMaybe, entity);
+		this.doRemove(value, entity);
+	}
+	doAdd(value, entity) {
+		const set = this.#valueToEntities.get(value) ?? /* @__PURE__ */ new Set();
+		if (set.size === 0) this.#valueToEntities.set(value, set);
+		set.add(entity);
+	}
+	doRemove(value, entity) {
+		const set = this.#valueToEntities.get(value);
+		if (set) {
+			set.delete(entity);
+			if (set.size === 0) this.#valueToEntities.delete(value);
+		}
+	}
+};
+function intersectSets(set1, set2) {
+	const [smaller, larger] = set1.size <= set2.size ? [set1, set2] : [set2, set1];
+	const result = /* @__PURE__ */ new Set();
+	for (const item of smaller) if (larger.has(item)) result.add(item);
+	return result;
+}
+//#endregion
+exports.IndexManager = IndexManager;
+exports.indexThreshold = indexThreshold;
+
+//# sourceMappingURL=IndexManager.cjs.map

package/build/IndexManager.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexManager.cjs","names":["#indexes","groupBy","getMetadata","isLoadedReference","#valueToEntities","isEntity"],"sources":["../src/IndexManager.ts"],"sourcesContent":["import { type Entity, isEntity } from \"src/Entity.ts\";\nimport { type EntityMetadata, type Field, getMetadata } from \"src/EntityMetadata.ts\";\nimport { type ManyToOneReference, type PolymorphicReference, isLoadedReference } from \"src/relations/index.ts\";\nimport { groupBy } from \"src/utils.ts\";\n\ntype FieldValue = any;\ntype FieldName = string;\ntype EntityTag = string;\ntype FieldIndexEntry = {\n  field: Field;\n  index: FieldIndex;\n  /** Tracks how far into the EM's list-per-tag array this field index has been lazily populated. */\n  indexedCount: number;\n};\nconst emptySet = new Set<Entity>();\n\n// The test reproducing a n^2 with n=500 went from 100ms to 50ms if indexed\nexport const indexThreshold = 500;\n\n/**\n * IndexManager provides field-based indexing for entity queries to avoid O(n) linear scans of `em.entities`.\n *\n * Key features:\n * - Only indexes entity types with >1000 entities to avoid overhead for small datasets\n * - Supports dual indexing for m2o/poly fields (by ID for saved, by instance for unsaved)\n * - Automatically maintains indexes when fields are updated via setField()\n */\nexport class IndexManager {\n  readonly #indexes: Map<EntityTag, Map<FieldName, FieldIndexEntry>> = new Map();\n\n  /** @return if we should index entities of this type/count. */\n  shouldIndexType(entityCount: number): boolean {\n    return entityCount >= indexThreshold;\n  }\n\n  /** Visible for testing. */\n  isIndexed(tagName: string): boolean {\n    return this.#indexes.has(tagName);\n  }\n\n  /** Enables indexing for an entity type and builds indexes for the requested fields. */\n  enableIndexingForType<T extends Entity>(meta: EntityMetadata<T>, entities: T[], where: object): void {\n    const { tagName } = meta;\n    if (!this.#indexes.has(tagName)) {\n      this.#indexes.set(tagName, new Map());\n    }\n\n    const fieldNames = Object.keys(where);\n    const fieldIndexes = this.#indexes.get(tagName)!;\n    const missingFieldNames = fieldNames.filter((fieldName) => !fieldIndexes.has(fieldName));\n    if (missingFieldNames.length === 0) return;\n\n    // If subtypes are involved, group by each subtype\n    if (meta.baseType || meta.subTypes.length > 0) {\n      [...groupBy(entities, (e) => getMetadata(e)).entries()].forEach(([meta, entities]) => {\n        this.addEntitiesToIndex(meta, entities, missingFieldNames);\n      });\n    } else {\n      this.addEntitiesToIndex(meta, entities, missingFieldNames);\n    }\n  }\n\n  /** Updates indexes when a field value changes. */\n  maybeUpdateFieldIndex(entity: Entity, fieldName: string, oldValue: any, newValue: any): void {\n    // Fast return for the common case, which is no indexing\n    if (this.#indexes.size === 0) return;\n\n    const meta = getMetadata(entity);\n    const fieldIndexes = this.#indexes.get(meta.tagName);\n    if (!fieldIndexes) return; // Type not indexed\n\n    const fieldIndex = fieldIndexes.get(fieldName)?.index;\n    if (!fieldIndex) return; // Field is not indexed\n\n    fieldIndex.remove(oldValue, entity);\n    fieldIndex.add(newValue, entity);\n  }\n\n  /**\n   * Finds entities matching the given where clause using indexes.\n   *\n   * Returns the raw candidate set (possibly a live internal index set, so do not mutate it);\n   * the caller applies its own subtype/deleted filtering while building the final array.\n   */\n  findMatching<T extends Entity>(meta: EntityMetadata<T>, entities: T[], where: any): ReadonlySet<T> {\n    const { tagName } = meta;\n    if (!this.#indexes.has(tagName)) {\n      throw new Error(`${meta.type} is not indexed`);\n    }\n    const fieldIndexes = this.#indexes.get(tagName)!;\n    // Start with all entities of the 1st condition, then intersect (AND) each subsequent field in `where`\n    let candidates: Set<Entity> | undefined;\n    for (const [fieldName, value] of Object.entries(where)) {\n      this.indexUnindexedEntities(entities, fieldName);\n      const fieldCandidates = fieldIndexes.get(fieldName)?.index.get(value);\n      if (!candidates) {\n        candidates = fieldCandidates ?? emptySet; // This is the 1st clause\n      } else {\n        candidates = fieldCandidates ? intersectSets(candidates, fieldCandidates) : emptySet;\n      }\n      // Early exit if no candidates remain\n      if (candidates.size === 0) break;\n    }\n    if (candidates === undefined) {\n      throw new Error(`Expected where clause with at least one condition`);\n    }\n    return candidates as unknown as ReadonlySet<T>;\n  }\n\n  // `entities` should all be of the exact same subtype\n  private addEntitiesToIndex(meta: EntityMetadata, entities: Entity[], fieldNames: string[]): void {\n    const { tagName } = meta;\n    const indexes = this.#indexes.get(tagName)!;\n    // Iterate over each field so we can do a shared fieldIndex lookup\n    for (const fieldName of fieldNames) {\n      const field = meta.allFields[fieldName];\n      if (!field) continue;\n      let entry = indexes.get(fieldName);\n      if (!entry) {\n        entry = { field, index: new FieldIndex(), indexedCount: 0 };\n        indexes.set(fieldName, entry);\n      }\n      for (const entity of entities) {\n        // Deleted entities never match, and reading a flushed one's relations throws\n        if (entity.isDeletedEntity) continue;\n        const value = getFieldValue(entity, fieldName, entry.field);\n        entry.index.add(value, entity);\n      }\n      entry.indexedCount = entities.length;\n    }\n  }\n\n  /** Lazily indexes newly-registered entities only for fields that are queried. */\n  private indexUnindexedEntities<T extends Entity>(entities: T[], fieldName: string): void {\n    const first = entities[0];\n    if (first === undefined) return;\n\n    const meta = getMetadata(first);\n    const entry = this.#indexes.get(meta.tagName)?.get(fieldName);\n    if (entry === undefined || entry.indexedCount === entities.length) return;\n\n    for (let i = entry.indexedCount; i < entities.length; i++) {\n      const entity = entities[i];\n      if (entity.isDeletedEntity) continue;\n      const value = getFieldValue(entity, fieldName, entry.field);\n      entry.index.add(value, entity);\n    }\n    entry.indexedCount = entities.length;\n  }\n}\n\n// Use the same field access pattern as entityMatches\nfunction getFieldValue(entity: Entity, fieldName: string, field: Field): any {\n  const fn = fieldName as keyof Entity;\n  switch (field.kind) {\n    case \"primaryKey\":\n      return entity.idTaggedMaybe;\n    case \"enum\":\n    case \"primitive\":\n      return (entity as any)[fn];\n    case \"m2o\":\n    case \"poly\":\n      const relation = (entity as any)[fn] as\n        | ManyToOneReference<Entity, any, any>\n        | PolymorphicReference<Entity, any, any>;\n      if (isLoadedReference(relation)) {\n        return relation.get;\n      } else if (relation.isSet) {\n        return relation.id;\n      } else {\n        return undefined;\n      }\n    default:\n      return undefined;\n  }\n}\n\n/**\n * For a given field, like `firstName`, holds the reverse index of value `bob` -> entities `[a1, a2]`.\n *\n * This also handles indexes `Entity` values as both instances & IDs, to handle both:\n * - new/unpersisted entities not yet having IDs, and\n * - relations not having loaded their instances yet\n */\nclass FieldIndex {\n  readonly #valueToEntities = new Map<FieldValue, Set<Entity>>();\n\n  /** @return entities that have `value` as their current value for this field. */\n  get(value: any): Set<Entity> | undefined {\n    if (isEntity(value) && value.idTaggedMaybe) {\n      // If `value` is a persisted entity like `a:1`, and entities could have indexed their `author_id=a:1` field\n      // values as the unloaded \"just an a:1 string id\" value, before `a:1` was loaded into memory.\n      const matchId = this.#valueToEntities.get(value.idTaggedMaybe);\n      // But other entities could also have indexes `a:1` as an instance, so go ahead and check both\n      const matchInstance = this.#valueToEntities.get(value);\n      if (matchId && matchInstance) {\n        return new Set([...matchId, ...matchInstance]);\n      }\n      return matchId ?? matchInstance;\n    }\n    // Treat null and undefined as equivalent for unset relations\n    if (value === null) value = undefined;\n    return this.#valueToEntities.get(value);\n  }\n\n  add(value: any, entity: Entity): void {\n    // If this is an entity, store both the entity itself & its ID\n    if (isEntity(value) && value.idTaggedMaybe) {\n      this.doAdd(value.idTaggedMaybe, entity);\n    }\n    this.doAdd(value, entity);\n  }\n\n  remove(value: any, entity: Entity): void {\n    if (isEntity(value) && value.idTaggedMaybe) {\n      this.doRemove(value.idTaggedMaybe, entity);\n    }\n    this.doRemove(value, entity);\n  }\n\n  private doAdd(value: any, entity: Entity): void {\n    const set = this.#valueToEntities.get(value) ?? new Set();\n    if (set.size === 0) this.#valueToEntities.set(value, set);\n    set.add(entity);\n  }\n\n  private doRemove(value: any, entity: Entity): void {\n    const set = this.#valueToEntities.get(value);\n    if (set) {\n      set.delete(entity);\n      if (set.size === 0) {\n        this.#valueToEntities.delete(value);\n      }\n    }\n  }\n}\n\nfunction intersectSets<T>(set1: Set<T>, set2: Set<T>): Set<T> {\n  const [smaller, larger] = set1.size <= set2.size ? [set1, set2] : [set2, set1];\n  const result = new Set<T>();\n  for (const item of smaller) {\n    if (larger.has(item)) {\n      result.add(item);\n    }\n  }\n  return result;\n}\n"],"mappings":"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"}

package/build/IndexManager.d.cts

@@ -0,0 +1,36 @@
+import { EntityMetadata } from "./EntityMetadata.cjs";
+import { Entity } from "./Entity.cjs";
+//#region src/IndexManager.d.ts
+declare const indexThreshold = 500;
+/**
+ * IndexManager provides field-based indexing for entity queries to avoid O(n) linear scans of `em.entities`.
+ *
+ * Key features:
+ * - Only indexes entity types with >1000 entities to avoid overhead for small datasets
+ * - Supports dual indexing for m2o/poly fields (by ID for saved, by instance for unsaved)
+ * - Automatically maintains indexes when fields are updated via setField()
+ */
+declare class IndexManager {
+  #private;
+  /** @return if we should index entities of this type/count. */
+  shouldIndexType(entityCount: number): boolean;
+  /** Visible for testing. */
+  isIndexed(tagName: string): boolean;
+  /** Enables indexing for an entity type and builds indexes for the requested fields. */
+  enableIndexingForType<T extends Entity>(meta: EntityMetadata<T>, entities: T[], where: object): void;
+  /** Updates indexes when a field value changes. */
+  maybeUpdateFieldIndex(entity: Entity, fieldName: string, oldValue: any, newValue: any): void;
+  /**
+   * Finds entities matching the given where clause using indexes.
+   *
+   * Returns the raw candidate set (possibly a live internal index set, so do not mutate it);
+   * the caller applies its own subtype/deleted filtering while building the final array.
+   */
+  findMatching<T extends Entity>(meta: EntityMetadata<T>, entities: T[], where: any): ReadonlySet<T>;
+  private addEntitiesToIndex;
+  /** Lazily indexes newly-registered entities only for fields that are queried. */
+  private indexUnindexedEntities;
+}
+//#endregion
+export { IndexManager, indexThreshold };
+//# sourceMappingURL=IndexManager.d.cts.map

package/build/IndexManager.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexManager.d.cts","names":[],"sources":["../src/IndexManager.ts"],"mappings":";;;cAiBa;;;;;;;;;cAUA;;;EAIX,gBAAgB;;EAKhB,UAAU;;EAKV,sBAAsB,UAAU,QAAQ,MAAM,eAAe,IAAI,UAAU,KAAK;;EAsBhF,sBAAsB,QAAQ,QAAQ,mBAAmB,eAAe;;;;;;;EAqBxE,aAAa,UAAU,QAAQ,MAAM,eAAe,IAAI,UAAU,KAAK,aAAa,YAAY;UA0BxF;;UAuBA"}

package/build/IndexManager.d.mts

@@ -0,0 +1,36 @@
+import { EntityMetadata } from "./EntityMetadata.mjs";
+import { Entity } from "./Entity.mjs";
+//#region src/IndexManager.d.ts
+declare const indexThreshold = 500;
+/**
+ * IndexManager provides field-based indexing for entity queries to avoid O(n) linear scans of `em.entities`.
+ *
+ * Key features:
+ * - Only indexes entity types with >1000 entities to avoid overhead for small datasets
+ * - Supports dual indexing for m2o/poly fields (by ID for saved, by instance for unsaved)
+ * - Automatically maintains indexes when fields are updated via setField()
+ */
+declare class IndexManager {
+  #private;
+  /** @return if we should index entities of this type/count. */
+  shouldIndexType(entityCount: number): boolean;
+  /** Visible for testing. */
+  isIndexed(tagName: string): boolean;
+  /** Enables indexing for an entity type and builds indexes for the requested fields. */
+  enableIndexingForType<T extends Entity>(meta: EntityMetadata<T>, entities: T[], where: object): void;
+  /** Updates indexes when a field value changes. */
+  maybeUpdateFieldIndex(entity: Entity, fieldName: string, oldValue: any, newValue: any): void;
+  /**
+   * Finds entities matching the given where clause using indexes.
+   *
+   * Returns the raw candidate set (possibly a live internal index set, so do not mutate it);
+   * the caller applies its own subtype/deleted filtering while building the final array.
+   */
+  findMatching<T extends Entity>(meta: EntityMetadata<T>, entities: T[], where: any): ReadonlySet<T>;
+  private addEntitiesToIndex;
+  /** Lazily indexes newly-registered entities only for fields that are queried. */
+  private indexUnindexedEntities;
+}
+//#endregion
+export { IndexManager, indexThreshold };
+//# sourceMappingURL=IndexManager.d.mts.map

package/build/IndexManager.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexManager.d.mts","names":[],"sources":["../src/IndexManager.ts"],"mappings":";;;cAiBa;;;;;;;;;cAUA;;;EAIX,gBAAgB;;EAKhB,UAAU;;EAKV,sBAAsB,UAAU,QAAQ,MAAM,eAAe,IAAI,UAAU,KAAK;;EAsBhF,sBAAsB,QAAQ,QAAQ,mBAAmB,eAAe;;;;;;;EAqBxE,aAAa,UAAU,QAAQ,MAAM,eAAe,IAAI,UAAU,KAAK,aAAa,YAAY;UA0BxF;;UAuBA"}