joist-core 2.3.0 → 2.4.0-next.2

package/build/config.d.mts

@@ -0,0 +1,277 @@
+import { FieldsOf } from "./typeMap.mjs";
+import { MaybePromise } from "./utils.mjs";
+import { LoadHint, Loaded, RelationsIn } from "./loading/loadHints.mjs";
+import { Reacted, ReactiveHint } from "./reactivity/reactiveHints.mjs";
+import { ValidationRule, ValidationRuleInternal } from "./rules.mjs";
+import { EntityMetadata } from "./EntityMetadata.mjs";
+import { AsyncDefault } from "./defaults.mjs";
+import { EntityField, SettableFields } from "./EntityFields.mjs";
+import "./index.mjs";
+import { EntityConstructor, MaybeAbstractEntityConstructor } from "./EntityManager.mjs";
+import { Entity } from "./Entity.mjs";
+//#region src/config.d.ts
+type EntityHook = "beforeFlush" | "beforeCreate" | "beforeUpdate" | "beforeDelete" | "afterValidation" | "beforeCommit" | "afterCommit";
+type HookFn<T extends Entity, C> = (entity: T, ctx: C) => MaybePromise<unknown>;
+type AddReactionOpts = {
+  runOnce?: boolean;
+  name?: string;
+};
+declare const constraintNameToValidationError: Record<string, string>;
+type Settable<T extends Entity> = keyof SettableFields<FieldsOf<T>> & string;
+/**
+ * Called at the end of `configureMetadata` to indicate the boot process is complete.
+ *
+ * We use this flag to prevent users from mistakenly calling `config` methods after the boot
+ * process is complete, i.e. from hooks or other post-boot invocations, where the calls are
+ * not guaranteed to work because Joist's reactivity graph has already been initialized.
+ */
+declare function setBooted(): void;
+declare function setAfterMetadataLocked(): void;
+/** The public API to configure an Entity's hooks & validation rules. */
+declare class ConfigApi<T extends Entity, C> {
+  __data: ConfigData<T, C>;
+  /**
+   * Maps a given `constraintName`, i.e. `authors_publisher_id_unique_index`, to a hard-coded-but-pretty validation errors.
+   *
+   * Note that the validationError must be hard-coded b/c we cannot tease out "which entity" caused a given
+   * constraint failure from the SQL database. If you really need pretty-and-custom validation errors, you'll
+   * need to check the constraint by hand ahead of time, before calling `em.flush`.
+   */
+  addConstraintMessage(constraintName: string, validationError: string): void;
+  /**
+   * Maps a `RecursiveCycleError` on the given recursive collection field to a custom validation error.
+   *
+   * When a cycle is detected in a recursive collection (e.g. `parentsRecursive`), instead of
+   * throwing a raw `RecursiveCycleError`, `em.flush` will convert it into a `ValidationErrors`
+   * using the provided message function.
+   *
+   * The `messageFn` receives the entity that detected the cycle and the cycle path (array of
+   * entities forming the cycle), and should return a validation error string.
+   */
+  addCycleRule(fieldName: string & keyof T, messageFn: (entity: T, cyclePath: Entity[]) => string): void;
+  /**
+   * Adds a validation rule for this entity.
+   *
+   * If `hint` is passed, then the rule's lambda will be: 1) passed a view of the entity with only
+   * the fields included in `hint` marked as accessible, and 2) the rule will be called reactively any
+   * time any field in the `hint` changes.
+   *
+   * If lambdas want to access fields w/o having them marked for reactivity, the rule can either
+   * include the field as readonly with a `:ro` suffix, i.e. `firstName:ro`, or the lambda can
+   * access the `reacted.entity` property to get a full view of the entity's fields and methods.
+   */
+  addRule<H extends ReactiveHint<T>>(hint: H, rule: ValidationRule<Reacted<T, H>>): void;
+  addRule(rule: ValidationRule<T>): void;
+  /**
+   * Adds a "commit rule" that runs like a regular validation rule (see {@link addRule}), but *after*
+   * the entity's `INSERT`/`UPDATE`/`DELETE` has been flushed to the database and *before* the
+   * transaction `COMMIT`s, i.e. still within the transaction.
+   *
+   * The point of running this late is that any `em.find`s the rule makes will query the _changed_
+   * state (the just-flushed rows), instead of the pre-flush state that regular `addRule` rules see.
+   * This is useful for cross-row invariants that are easiest to express as a query, e.g. "at most
+   * one active `AuthorSchedule` per author", where the rule wants to `em.find` the sibling rows
+   * that were themselves just inserted/updated in this same flush.
+   *
+   * Like `addRule`, if a `hint` is passed the rule is reactive: it runs whenever any field in the
+   * hint changes (walking back to the owning entity), and the lambda gets a `Reacted` view.
+   */
+  addCommitRule<H extends ReactiveHint<T>>(hint: H, rule: ValidationRule<Reacted<T, H>>): void;
+  addCommitRule(rule: ValidationRule<T>): void;
+  /** If both this entity, and `cstr` entities, are in the same `em.flush`, run us first. */
+  runHooksBefore(cstr: EntityConstructor<any>): void;
+  /** Deletes any entity/entities pointed to by `relation` when this entity is deleted. */
+  cascadeDelete(relation: keyof RelationsIn<T> & LoadHint<T>): void;
+  touchOnChange(relation: keyof RelationsIn<T>): void;
+  private addHook;
+  afterMetadata(fn: AfterMetadataCallback<T>): void;
+  beforeDelete<H extends LoadHint<T>>(populate: H, fn: HookFn<Loaded<T, H>, C>): void;
+  beforeDelete(fn: HookFn<T, C>): void;
+  beforeFlush<H extends LoadHint<T>>(populate: H, fn: HookFn<Loaded<T, H>, C>): void;
+  beforeFlush(fn: HookFn<T, C>): void;
+  beforeCreate<H extends LoadHint<T>>(populate: H, fn: HookFn<Loaded<T, H>, C>): void;
+  beforeCreate(fn: HookFn<T, C>): void;
+  beforeUpdate<H extends LoadHint<T>>(populate: H, fn: HookFn<Loaded<T, H>, C>): void;
+  beforeUpdate(fn: HookFn<T, C>): void;
+  afterValidation<H extends LoadHint<T>>(populate: H, fn: HookFn<Loaded<T, H>, C>): void;
+  afterValidation(fn: HookFn<T, C>): void;
+  beforeCommit(fn: HookFn<T, C>): void;
+  afterCommit(fn: HookFn<T, C>): void;
+  /**
+   * Adds a reaction that runs during flush whenever fields in the `hint` change.
+   *
+   * Reactions are somewhere in between hooks and reactive fields/references:
+   * 1. Can make arbitrary changes to any entity like a hook
+   * 2. Only run when the provided hint has changes, not on every flush, like an RF/RR
+   * 3. Run when the entity itself has no changes, like an RF/RF
+   * 4. Can run multiple times per flush, like an RF/RF.  Be careful to avoid creating
+   *    circular dependencies in the hint and to make the function idempotent.
+   *
+   * @param hint The fields to watch for changes and load before running the reaction
+   * @param fn The reaction function to run
+   */
+  addReaction<H extends ReactiveHint<T>>(hint: H, fn: HookFn<Loaded<T, H>, C>): void;
+  /**
+   * Adds a named reaction that runs during flush whenever fields in the `hint` change.
+   *
+   * Reactions are somewhere in between hooks and reactive fields/references:
+   * 1. Can make arbitrary changes to any entity like a hook
+   * 2. Only run when `hint` has changes, not on every flush, like an RF/RR
+   * 3. Can run when the entity itself has no changes, like an RF/RF
+   * 4. Can run multiple times per flush, like an RF/RF.  Be careful to avoid creating
+   *    circular dependencies in the hint and to make the function idempotent.
+   *
+   * @param name A name to identify this reaction for debugging
+   * @param hint The fields to watch for changes and load before running the reaction
+   * @param fn The reaction function to run
+   */
+  addReaction<H extends ReactiveHint<T>>(name: string, hint: H, fn: HookFn<Loaded<T, H>, C>): void;
+  /**
+   * Adds a reaction that runs during flush whenever fields in the `hint` change.
+   *
+   * Reactions are somewhere in between hooks and reactive fields/references:
+   * 1. Can make arbitrary changes to any entity like a hook
+   * 2. Only run when `hint` has changes, not on every flush, like an RF/RR
+   * 3. Can run when the entity itself has no changes, like an RF/RF
+   * 4. Can run multiple times per flush, like an RF/RF.  Be careful to avoid creating
+   *    circular dependencies in the hint and to make the function idempotent.
+   *
+   * @param opts Options object containing:
+   *   - runOnce - If true, the reaction will only run once per flush, not every time the hint changes. Optional.
+   *   default: false.
+   *   - name - A name to identify this reaction for debugging
+   * @param hint The fields to watch for changes and load before running the reaction
+   * @param fn The reaction function to run
+   */
+  addReaction<H extends ReactiveHint<T>>(opts: AddReactionOpts, hint: H, fn: HookFn<Loaded<T, H>, C>): void;
+  /** Adds a synchronous default for `fieldName` to a hard-coded `value`. */
+  setDefault<K extends Settable<T>, F = FieldsOf<T>[K]>(fieldName: K, value: F extends EntityField ? F["type"] : never): void;
+  /** Adds a synchronous default for `fieldName` to the result of simple sync lambda. */
+  setDefault<K extends Settable<T>, F = FieldsOf<T>[K]>(fieldName: K, fn: (entity: T) => F extends EntityField ? F["type"] | undefined : never): void;
+  /** Adds an asynchronous default for `fieldName` to the result of a hinted lambda. */
+  setDefault<K extends Settable<T>, const H extends ReactiveHint<T>, F = FieldsOf<T>[K]>(fieldName: K, hint: H, fn: (entity: Reacted<T, H>, ctx: C) => F extends {
+    kind: "m2o";
+    type: infer T extends Entity;
+  } ? MaybePromise<T | Reacted<T, {}> | undefined> : F extends EntityField ? MaybePromise<F["type"] | undefined> : never): void;
+  /**
+   * A noop method that exists solely to keep the `config.placeholder()` line in the initial entity file,
+   * until the user is ready to use it. */
+  placeholder(): void;
+  private ensurePreBoot;
+}
+/**
+ * Allows projects to manually reset the internal `booted` flag.
+ *
+ * This is only necessary if they're using hot-reloading and reloading their entity files
+ * without restarting the server.
+ *
+ * Generally most tools like tsx or ts-node-dev reload the whole process, so don't need
+ * to call this, but if Joist is used in a framework that does actual-hot-reloading, this
+ * it will be necessary.
+ */
+declare function resetBootFlag(): void;
+/**
+ * Stores a path back to a reactive rule.
+ *
+ * I.e. if `Book` has a `ruleFn` that reacts to `Author.title`, then `Author`'s config will have
+ * a `ReactiveRule` with fields `["title"]`, path `books`, and rule `ruleFn`.
+ */
+interface ReactiveRule {
+  /** The source we're reacting to, specifically which base/subtype cstr. */
+  source: MaybeAbstractEntityConstructor<any>;
+  /** The fields on this source entity that would trigger the downstream rule's eval. */
+  fields: string[];
+  /** The constructor of downstream entity that owns the reactive rule. */
+  cstr: MaybeAbstractEntityConstructor<any>;
+  /** The name (source location) of the downstream reactive rule. */
+  name: string;
+  /** The path from this source entity to the downstream entity that needs evaled. */
+  path: string[];
+  /** The downstream validation rule to eval. */
+  fn: ValidationRule<any>;
+}
+/**
+ * Stores a path back to a reactive derived field.
+ *
+ * I.e. if `Book.displayName` is an `asyncField` that reacts to `Author.title`, then `Author`'s config will have
+ * a `ReactiveFields` with fields `["title"]`, path `books`, and name `displayName`.
+ */
+interface ReactiveField {
+  kind: "populate" | "query";
+  /** The fields on this source entity that would trigger the downstream field's recalc. */
+  fields: string[];
+  /** Read-only/immutable fields that are used in the derived field. */
+  isReadOnly: boolean;
+  /** The constructor of downstream entity that owns the derived field. */
+  cstr: MaybeAbstractEntityConstructor<any>;
+  /** The path from this source entity to the downstream entity that needs recalced. */
+  path: string[];
+  /** The name of the reactive field in the downstream entity to recalc. */
+  name: string;
+  runOnce: false;
+}
+interface Reaction {
+  kind: "reaction";
+  /** The source we're reacting to, specifically which base/subtype cstr. */
+  source: MaybeAbstractEntityConstructor<any>;
+  /** The fields on this source entity that would trigger the downstream hook's eval. */
+  fields: string[];
+  /** Read-only/immutable fields that are used in the function. */
+  isReadOnly: boolean;
+  /** The constructor of downstream entity that owns the reaction. */
+  cstr: MaybeAbstractEntityConstructor<any>;
+  /** The name (source location) of the downstream reaction. */
+  name: string;
+  /** The path from this source entity to the downstream entity for this reaction. */
+  path: string[];
+  /** The downstream reaction function. */
+  fn: HookFn<any, any>;
+  /** If true, the reaction should only run once per flush, not every time the hint changes. */
+  runOnce: boolean;
+}
+type Reactable = ReactiveField | Reaction;
+interface ReactionInternal<T extends Entity, H extends ReactiveHint<T>, C> {
+  name: string;
+  fn: HookFn<T, C>;
+  hint: H;
+  runOnce: boolean;
+}
+type AfterMetadataCallback<T extends Entity> = (meta: EntityMetadata<T>) => void;
+/** The internal state of an entity's configuration data, i.e. validation rules/hooks. */
+declare class ConfigData<T extends Entity, C> {
+  afterMetadataCallbacks: AfterMetadataCallback<T>[];
+  runHooksBefore: EntityConstructor<any>[];
+  /** The validation rules for this entity type. */
+  rules: ValidationRuleInternal<T>[];
+  /** The "commit rules" for this entity type, i.e. validation rules that run post-flush/pre-commit. */
+  commitRules: ValidationRuleInternal<T>[];
+  /** The reactions for this entity type. */
+  reactions: ReactionInternal<T, any, C>[];
+  /** The hooks for this entity type. */
+  hooks: Record<EntityHook, HookFn<T, C>[]>;
+  /** Synchronous defaults for this entity type, invoked on `em.create`. */
+  syncDefaults: Record<string, ((entity: T) => void) | unknown>;
+  /** Asynchronous defaults for this entity type, invoked on `em.flush`. */
+  asyncDefaults: Record<string, AsyncDefault<T>>;
+  reactiveRules: ReactiveRule[];
+  reactiveCommitRules: ReactiveRule[];
+  reactables: Reactable[];
+  cascadeDeleteFields: Array<keyof RelationsIn<T>>;
+  touchOnChange: Set<keyof RelationsIn<T>>;
+  cachedReactiveLoadHints: Record<string, any>;
+  /** Maps recursive collection fieldNames to custom cycle error message functions. */
+  cycleMessages: Record<string, (entity: T, cyclePath: Entity[]) => string>;
+}
+declare function getCallerName(extraFrames?: number): string;
+declare function getFuzzyCallerName(): string;
+/**
+ * Given a callstack line return the file name.
+ *
+ * I.e. `at Object.<anonymous> (/home/stephen/homebound/graphql-service/src/entities/Activity.ts:86:8)`
+ */
+declare function getFilePath(line: string): string;
+/** Given a callstack, uses heuristics to find the first line that looks like user code. */
+declare function findUserCodeLine(lines: string[]): string;
+//#endregion
+export { ConfigApi, ConfigData, EntityHook, Reactable, Reaction, ReactiveField, ReactiveRule, constraintNameToValidationError, findUserCodeLine, getCallerName, getFilePath, getFuzzyCallerName, resetBootFlag, setAfterMetadataLocked, setBooted };
+//# sourceMappingURL=config.d.mts.map

package/build/config.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.mts","names":[],"sources":["../src/config.ts"],"mappings":"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"}