@afora/core 0.0.9 → 0.0.11

package/dist/core/repository/references.js

@@ -0,0 +1,196 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import { recordFieldOf } from "../blueprint/record-field.js";
+import {
+  blueprintOfVariant,
+  isBlueprintVariant,
+  namedVariantOf
+} from "../blueprint/variant.js";
+import { isEntityClass } from "../entity/entity.js";
+import { recordNameOf } from "../record/name.js";
+import { scopedProvider } from "../use-case/scope.js";
+import {
+  InvalidRepositoryData,
+  InvalidRepositoryDeclaration,
+  RepositoryEntityNotFound
+} from "./exceptions.js";
+import { contextOf, findState } from "./state.js";
+import { upcastRows } from "./upcast.js";
+function isPlain(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function recordClassOf(field) {
+  return recordFieldOf(field)?.record;
+}
+function entityClassesOf(properties) {
+  const found = new Set;
+  function visit(field) {
+    if (isBlueprintList(field)) {
+      visit(field.item);
+    } else if (isBlueprint(field)) {
+      walk(field.properties);
+    } else if (isBlueprintVariant(field)) {
+      for (const variant of Object.values(field.variants)) {
+        visit(variant);
+      }
+    } else {
+      const record = recordClassOf(field);
+      if (!record)
+        return;
+      if (isEntityClass(record))
+        found.add(record);
+      else
+        walk(record.blueprint.properties);
+    }
+  }
+  function walk(properties) {
+    for (const field of Object.values(properties))
+      visit(field);
+  }
+  walk(properties);
+  return found;
+}
+function mapReferences(properties, data, visit) {
+  function mapField(field, value) {
+    if (value === undefined || value === null)
+      return value;
+    if (isBlueprintList(field)) {
+      return Array.isArray(value) ? Object.freeze(value.map((item) => mapField(field.item, item))) : value;
+    }
+    if (isBlueprint(field)) {
+      return isPlain(value) ? mapCollection(field.properties, value) : value;
+    }
+    if (isBlueprintVariant(field)) {
+      const variant = namedVariantOf(field, value);
+      if (!variant || !isPlain(value))
+        return value;
+      if (isEntityClass(variant)) {
+        const mapped = visit(variant, value.id);
+        return mapped === value.id ? value : mapped;
+      }
+      return mapCollection(blueprintOfVariant(variant).properties, value);
+    }
+    const record = recordClassOf(field);
+    if (!record)
+      return value;
+    if (isEntityClass(record))
+      return visit(record, value);
+    return isPlain(value) ? mapCollection(record.blueprint.properties, value) : value;
+  }
+  function mapCollection(properties, value) {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [
+      key,
+      mapField(properties[key], item)
+    ])));
+  }
+  return mapCollection(properties, data);
+}
+export function relationsOf(name, entity, relations) {
+  const invalid = (reason) => {
+    throw new InvalidRepositoryDeclaration({
+      source: name,
+      details: { reason }
+    });
+  };
+  if (relations === undefined)
+    relations = [];
+  if (!Array.isArray(relations)) {
+    return invalid("Expected relations to be a list of repositories.");
+  }
+  const related = [];
+  for (const relation of relations) {
+    const state = findState(relation);
+    if (!state)
+      return invalid("Expected relations made by repositoryOf.");
+    if (related.some((other) => other.entity === state.entity)) {
+      return invalid(`Relation "${recordNameOf(state.entity)}" is duplicated.`);
+    }
+    if (typeof state.provider.findMany !== "function") {
+      return invalid(`The provider of "${state.name}" has no "findMany" to load it.`);
+    }
+    related.push(state);
+  }
+  const used = new Set;
+  const map = new Map;
+  for (const target of entityClassesOf(entity.blueprint.properties)) {
+    const matches = related.filter((state) => state.entity === target || state.entity.prototype instanceof target);
+    const exact = matches.find((state) => state.entity === target);
+    if (!exact && matches.length === 0) {
+      return invalid(`Missing relation: no repository of "${recordNameOf(target)}".`);
+    }
+    if (!exact && matches.length > 1) {
+      return invalid(`Relation "${recordNameOf(target)}" matches more than one repository.`);
+    }
+    const state = exact ?? matches[0];
+    map.set(target, state);
+    used.add(state);
+  }
+  for (const state of related) {
+    if (!used.has(state)) {
+      return invalid(`Relation "${recordNameOf(state.entity)}" is not held by ${recordNameOf(entity)}.`);
+    }
+  }
+  return map;
+}
+export function parseEntity(state, data) {
+  const parsed = state.entity.safeParse(data);
+  if (parsed.issues) {
+    throw new InvalidRepositoryData({
+      source: state.name,
+      cause: parsed.issues.find((issue) => issue.cause)?.cause
+    });
+  }
+  return parsed.value;
+}
+function loadByIds(state, ids, scope) {
+  return scopedProvider(scope, state.provider).findMany(contextOf(state), {
+    where: { id: { in: ids } },
+    withDeleted: true,
+    withExpired: true
+  });
+}
+export async function resolveReferences(state, datas, session, scope) {
+  if (state.relations.size === 0)
+    return datas;
+  const { properties } = state.entity.blueprint;
+  const wanted = new Map;
+  for (const data of datas) {
+    mapReferences(properties, data, (target, value) => {
+      const relation = state.relations.get(target);
+      if (relation && typeof value === "string") {
+        const ids = wanted.get(relation) ?? new Set;
+        wanted.set(relation, ids.add(value));
+      }
+      return value;
+    });
+  }
+  for (const [relation, ids] of wanted) {
+    const loaded = session.get(relation) ?? new Map;
+    session.set(relation, loaded);
+    const missing = [...ids].filter((id) => !loaded.has(id));
+    if (missing.length === 0)
+      continue;
+    const found = upcastRows(relation, await loadByIds(relation, missing, scope));
+    const resolved = await resolveReferences(relation, found, session, scope);
+    for (const data of resolved) {
+      const id = data.id;
+      if (!loaded.has(id))
+        loaded.set(id, parseEntity(relation, data));
+    }
+    for (const id of missing) {
+      if (loaded.has(id))
+        continue;
+      throw new InvalidRepositoryData({
+        source: state.name,
+        cause: new RepositoryEntityNotFound({
+          source: relation.name,
+          details: { id }
+        })
+      });
+    }
+  }
+  return datas.map((data) => mapReferences(properties, data, (target, value) => {
+    const relation = state.relations.get(target);
+    return relation && typeof value === "string" ? session.get(relation)?.get(value) ?? value : value;
+  }));
+}

package/dist/core/repository/repository.d.ts

@@ -80,9 +80,29 @@ export declare abstract class AbstractRepository<Entity extends AnyRepositoryEnt
  * `create`, `update`, `delete`, `restore` (soft deletion only), `increment`, `count`, and the queries `findMany`,
  * `exists`, `findPage` and `findCursor`, and `forEachPage`, which walks the
  * pages of a cursor query, resumably. Every method is async and reads and writes through `provider`
- * (a new `inMemoryProvider()` by default), which gets the variables of
+ * (a new {@link inMemoryProvider} by default), which gets the variables of
  * `environmentDependencies` as `context.env`. The repository can be a
- * dependency of a use case, and `RepositoryOf` extends it with a class.
+ * dependency of a use case, and {@link RepositoryOf} extends it with a class.
+ *
+ * @throws {@link InvalidRepositoryDeclaration} when `entity` is not an entity class made by `entityOf`, or a setting (`actions`, `deletion`, `scans`, `indexes`...) is not valid.
+ *
+ * @example
+ * ```ts
+ * import { blueprintOf, entityOf, repositoryOf } from "@afora/core";
+ *
+ * class User extends entityOf(
+ * 	blueprintOf((ctx) => ({ name: ctx.string, email: ctx.email })),
+ * 	{ unique: ["email"] },
+ * ) {}
+ *
+ * const Users = repositoryOf({
+ * 	entity: User,
+ * 	actions: ["findByEmail", "create"],
+ * });
+ *
+ * await Users.create({ name: "Ana", email: "ana@example.com" });
+ * const ana = await Users.findByEmail("ana@example.com"); // User | undefined
+ * ```
  */
 export declare function repositoryOf<Entity extends AnyRepositoryEntity, const Actions extends readonly RepositoryAction<Entity>[], const Environment extends EnvironmentDependencies | undefined = undefined, const Capabilities extends ProviderCapabilities = {
     readonly keyset: true;