@afora/core 0.0.8 → 0.0.11

package/dist/std/use-cases/crud.js

@@ -0,0 +1,261 @@
+import { listOf } from "../../core/blueprint/list.js";
+import { optionalOf } from "../../core/blueprint/optional.js";
+import { UseCaseEntityNotFound } from "../../core/use-case/exceptions.js";
+import { useCasePluginOf } from "../../core/use-case/plugin.js";
+import { Integer } from "../properties/primitives.js";
+import {
+  asOf,
+  capitalize,
+  checkOptions,
+  contextOf,
+  distinct,
+  entityUseCase,
+  errorOf,
+  fields,
+  HOOKS,
+  hooksOf,
+  idOf,
+  joinDependencies,
+  keysOf,
+  literal,
+  loadSteps,
+  metaOf,
+  ownerOf,
+  valuesOf
+} from "./shared.js";
+export function createCompilation(target, options, verb, checks = () => [], errors = []) {
+  checkOptions(target, options, ["as", "owner", "omit", "values", ...HOOKS]);
+  const owner = ownerOf(target, options);
+  const hooks = hooksOf(target, options);
+  const omitted = keysOf(target, options, "omit");
+  const constants = valuesOf(target, options, "values");
+  const notFound = errorOf(target, options, "notFound", UseCaseEntityNotFound);
+  const ownerError = errorOf(target, options, "owner", notFound);
+  const input = {};
+  const values = {};
+  const dependencies = {
+    repository: target.repository
+  };
+  const steps = [];
+  const used = new Set([...errors, ...hooks.throws]);
+  const take = (key, field) => {
+    if (Object.hasOwn(input, key)) {
+      target.unavailable(`two keys of the entity take the input "${key}"`);
+    }
+    input[key] = field;
+  };
+  const load = (key, reference, error) => {
+    const dependency = `${key}Repository`;
+    dependencies[dependency] = target.relation(key, ["findById"]);
+    used.add(error);
+    steps.push({
+      find: `${dependency}.findById`,
+      args: [reference],
+      as: `${key}Found`
+    }, { ensure: "exists", value: `$${key}Found`, error });
+    return `$${key}Found`;
+  };
+  for (const plan of target.fields) {
+    const { key } = plan;
+    if (plan.identity)
+      continue;
+    if (Object.hasOwn(constants, key)) {
+      values[key] = literal(constants[key]);
+      continue;
+    }
+    if (owner?.plan.key === key) {
+      values[key] = plan.kind === "entity" ? load(key, `$context.${owner.context}`, ownerError) : `$context.${owner.context}`;
+      continue;
+    }
+    const unloadable = plan.kind === "entity-list" || plan.kind === "entity" && plan.optional;
+    if (omitted.includes(plan) || unloadable) {
+      if (!plan.optional) {
+        target.unavailable(unloadable ? `"${key}" holds a list of entities, which the input cannot take; give it in values` : `"${key}" is required and cannot be omitted`);
+      }
+      continue;
+    }
+    take(plan.input.key, plan.input.field);
+    const given = `${hooks.input}.${plan.input.key}`;
+    if (plan.kind === "entity") {
+      values[key] = load(key, given, notFound);
+    } else if (plan.convert) {
+      steps.push({
+        run: `convert${capitalize(key)}`,
+        fn: plan.convert,
+        args: [given],
+        as: `${key}Converted`
+      });
+      values[key] = `$${key}Converted`;
+    } else {
+      values[key] = given;
+    }
+  }
+  return {
+    ...metaOf(target, options, verb),
+    blueprint: fields(() => input),
+    response: fields(() => ({ [asOf(target, options)]: target.entity })),
+    ...contextOf(owner),
+    dependencies: joinDependencies(target, dependencies, hooks),
+    errors: distinct(...used),
+    steps: [
+      ...hooks.before(),
+      ...checks(hooks.input),
+      ...steps,
+      { build: target.entity, values, as: "built" },
+      { create: "repository", value: "$built", as: "item" },
+      ...hooks.after("$item"),
+      { return: { [asOf(target, options)]: "$item" } }
+    ]
+  };
+}
+export const create = useCasePluginOf("create", {
+  description: "Builds an entity from the input (its keys, less the identity; an entity it holds by id) and stores it.",
+  requires: { actions: ["create"] },
+  compile: (target, options) => createCompilation(target, options, "Create")
+});
+export const get = useCasePluginOf("get", {
+  description: "Gives the entity of an id.",
+  requires: { actions: ["findById"] },
+  compile: (target, options) => entityUseCase(target, options, "Get", [], () => ({
+    steps: [],
+    result: "$item"
+  }))
+});
+export const list = useCasePluginOf("list", {
+  description: "Gives a page of entities: { items, total, limit, offset }.",
+  requires: { actions: ["findPage"] },
+  compile: (target, options) => {
+    checkOptions(target, options, ["owner", "orderBy"]);
+    const owner = ownerOf(target, options);
+    const { orderBy = [{ key: "createdAt", direction: "desc" }] } = options;
+    if (!Array.isArray(orderBy)) {
+      target.unavailable("the option orderBy must be a list of orders");
+    }
+    for (const order of orderBy) {
+      target.field(String(order?.key));
+    }
+    return {
+      ...metaOf(target, options, "List"),
+      blueprint: fields(() => ({
+        limit: optionalOf(Integer),
+        offset: optionalOf(Integer)
+      })),
+      response: fields(() => ({
+        items: listOf(target.entity),
+        total: Integer,
+        limit: Integer,
+        offset: Integer
+      })),
+      ...contextOf(owner),
+      dependencies: { repository: target.repository },
+      steps: [
+        {
+          find: "repository.findPage",
+          args: [
+            {
+              ...owner ? {
+                where: {
+                  [owner.plan.key]: `$context.${owner.context}`
+                }
+              } : {},
+              orderBy: literal(orderBy),
+              limit: "$input.limit",
+              offset: "$input.offset"
+            }
+          ],
+          as: "page"
+        },
+        {
+          return: {
+            items: "$page.items",
+            total: "$page.total",
+            limit: "$page.limit",
+            offset: "$page.offset"
+          }
+        }
+      ]
+    };
+  }
+});
+export const update = useCasePluginOf("update", {
+  description: "Changes the change keys the input gives, leaving the others as they are, and stores the entity.",
+  requires: { actions: ["findById", "update"] },
+  compile: (target, options) => {
+    checkOptions(target, options, ["as", "owner", ...HOOKS]);
+    const owner = ownerOf(target, options);
+    const hooks = hooksOf(target, options);
+    const notFound = errorOf(target, options, "notFound", UseCaseEntityNotFound);
+    const plans = target.changeKeys.map((key) => target.field(key)).filter((plan) => plan.kind !== "entity" && plan.kind !== "entity-list");
+    if (plans.length === 0) {
+      target.unavailable("the entity has no change key an input can take");
+    }
+    if (plans.some((plan) => plan.key === "id")) {
+      target.unavailable('"id" cannot be a change key');
+    }
+    const steps = [];
+    for (const plan of plans) {
+      const given = `${hooks.input}.${plan.input.key}`;
+      let value = given;
+      if (plan.convert) {
+        steps.push({
+          run: `convert${capitalize(plan.key)}`,
+          fn: plan.convert,
+          args: [given],
+          as: `${plan.key}Converted`
+        });
+        value = `$${plan.key}Converted`;
+      }
+      steps.push({ change: "$item", key: plan.key, value, ifPresent: true });
+    }
+    return {
+      ...metaOf(target, options, "Update"),
+      blueprint: fields(() => ({
+        id: idOf(target),
+        ...Object.fromEntries(plans.map((plan) => [plan.input.key, optionalOf(plan.input.field)]))
+      })),
+      response: fields(() => ({ [asOf(target, options)]: target.entity })),
+      ...contextOf(owner),
+      dependencies: joinDependencies(target, { repository: target.repository }, hooks),
+      errors: distinct(notFound, ...hooks.throws),
+      steps: [
+        ...loadSteps(owner, notFound),
+        ...hooks.before("$item"),
+        ...steps,
+        { update: "repository", value: "$item", as: "saved" },
+        ...hooks.after("$saved"),
+        { return: { [asOf(target, options)]: "$saved" } }
+      ]
+    };
+  }
+});
+const remove = useCasePluginOf("delete", {
+  description: "Deletes the entity of an id, hard or soft as the repository declares, and gives it.",
+  requires: { actions: ["findById", "delete"] },
+  compile: (target, options) => entityUseCase(target, options, "Delete", [], () => ({
+    steps: [{ delete: "repository", value: "$item", as: "deleted" }],
+    result: "$deleted"
+  }), true)
+});
+
+export { remove as delete_ };
+export const restore = useCasePluginOf("restore", {
+  description: "Brings back the soft-deleted entity of an id; for a repository with soft deletion and the restore action.",
+  requires: { actions: ["restore"] },
+  compile: (target, options) => {
+    checkOptions(target, options, ["as", ...HOOKS]);
+    const hooks = hooksOf(target, options);
+    return {
+      ...metaOf(target, options, "Restore"),
+      blueprint: fields(() => ({ id: idOf(target) })),
+      response: fields(() => ({ [asOf(target, options)]: target.entity })),
+      dependencies: joinDependencies(target, { repository: target.repository }, hooks),
+      errors: distinct(...hooks.throws),
+      steps: [
+        ...hooks.before(),
+        { restore: "repository", value: `${hooks.input}.id`, as: "item" },
+        ...hooks.after("$item"),
+        { return: { [asOf(target, options)]: "$item" } }
+      ]
+    };
+  }
+});

package/dist/std/use-cases/index.d.ts

@@ -6,6 +6,6 @@ import type { StdUseCasePlugins } from "./types.js";
  * `list`, `update`, `delete` and `restore` for any entity; `publish`,
  * `unpublish`, `archive`, `unarchive`, `tag` and `untag` for the entities
  * with those record plugins; `register` and `login` for the
- * authenticatable ones. `StdUseCases.context` is that `ctx`.
+ * authenticatable ones, and `refresh` and `logout` for the tokens of `login`. `StdUseCases.context` is that `ctx`.
  */
 export declare const StdUseCases: IUseCaseCatalog<StdUseCasePlugins>;

package/dist/std/use-cases/index.js

@@ -0,0 +1,12 @@
+import { useCaseCatalogOf } from "../../core/use-case/plugin-catalog.js";
+import { login, logout, refresh, register } from "./auth.js";
+import { create, delete_, get, list, restore, update } from "./crud.js";
+import {
+  archive,
+  publish,
+  tag,
+  unarchive,
+  unpublish,
+  untag
+} from "./lifecycle.js";
+export const StdUseCases = useCaseCatalogOf(create, get, list, update, delete_, restore, publish, unpublish, archive, unarchive, tag, untag, register, login, refresh, logout);

package/dist/std/use-cases/lifecycle.js

@@ -0,0 +1,97 @@
+import { listOf } from "../../core/blueprint/list.js";
+import { UseCaseEntityNotFound } from "../../core/use-case/exceptions.js";
+import { useCasePluginOf } from "../../core/use-case/plugin.js";
+import {
+  asOf,
+  checkOptions,
+  contextOf,
+  distinct,
+  entityUseCase,
+  errorOf,
+  fields,
+  HOOKS,
+  hooksOf,
+  idOf,
+  joinDependencies,
+  literal,
+  loadSteps,
+  metaOf,
+  ownerOf,
+  valuesOf
+} from "./shared.js";
+function invoking(target, options, verb, method) {
+  const set = valuesOf(target, options, "set");
+  const changes = Object.entries(set).map(([key, value]) => {
+    if (!target.changeKeys.includes(key)) {
+      target.unavailable(`set.${key} is not a change key of the entity`);
+    }
+    return { change: "$item", key, value: literal(value) };
+  });
+  return entityUseCase(target, options, verb, ["set"], () => ({
+    steps: [
+      ...changes,
+      { invoke: "$item", method },
+      { update: "repository", value: "$item", as: "saved" }
+    ],
+    result: "$saved"
+  }), true);
+}
+const lifecycle = (plugin) => ({
+  requires: { actions: ["findById", "update"], plugins: [plugin] }
+});
+export const publish = useCasePluginOf("publish", {
+  description: "Publishes the publishable entity of an id and stores it.",
+  ...lifecycle("publishable"),
+  compile: (target, options) => invoking(target, options, "Publish", "publish")
+});
+export const unpublish = useCasePluginOf("unpublish", {
+  description: "Makes the publishable entity of an id a draft again and stores it.",
+  ...lifecycle("publishable"),
+  compile: (target, options) => invoking(target, options, "Unpublish", "unpublish")
+});
+export const archive = useCasePluginOf("archive", {
+  description: "Archives the archivable entity of an id and stores it.",
+  ...lifecycle("archivable"),
+  compile: (target, options) => invoking(target, options, "Archive", "archive")
+});
+export const unarchive = useCasePluginOf("unarchive", {
+  description: "Makes the archived entity of an id active again and stores it.",
+  ...lifecycle("archivable"),
+  compile: (target, options) => invoking(target, options, "Unarchive", "restore")
+});
+function tagging(target, options, verb, method) {
+  checkOptions(target, options, ["as", "owner", ...HOOKS]);
+  const owner = ownerOf(target, options);
+  const hooks = hooksOf(target, options);
+  const notFound = errorOf(target, options, "notFound", UseCaseEntityNotFound);
+  const { item } = target.field("tags").field;
+  return {
+    ...metaOf(target, options, verb),
+    blueprint: fields(() => ({
+      id: idOf(target),
+      tags: listOf(item, { minItems: 1 })
+    })),
+    response: fields(() => ({ [asOf(target, options)]: target.entity })),
+    ...contextOf(owner),
+    dependencies: joinDependencies(target, { repository: target.repository }, hooks),
+    errors: distinct(notFound, ...hooks.throws),
+    steps: [
+      ...loadSteps(owner, notFound),
+      ...hooks.before("$item"),
+      { invoke: "$item", method, args: `${hooks.input}.tags` },
+      { update: "repository", value: "$item", as: "saved" },
+      ...hooks.after("$saved"),
+      { return: { [asOf(target, options)]: "$saved" } }
+    ]
+  };
+}
+export const tag = useCasePluginOf("tag", {
+  description: "Adds tags to the taggable entity of an id and stores it.",
+  ...lifecycle("taggable"),
+  compile: (target, options) => tagging(target, options, "Tag", "tag")
+});
+export const untag = useCasePluginOf("untag", {
+  description: "Removes tags from the taggable entity of an id and stores it.",
+  ...lifecycle("taggable"),
+  compile: (target, options) => tagging(target, options, "Untag", "untag")
+});

package/dist/std/use-cases/shared.d.ts

@@ -12,8 +12,8 @@ export declare function literal(value: unknown): unknown;
 export declare function checkOptions(target: UseCaseTargetInfo, options: Options, allowed: readonly string[]): void;
 /** The options of the use cases that write: `before`, `after`, `dependencies`, `throws`. */
 export declare const HOOKS: readonly ["before", "after", "dependencies", "throws"];
-/** The name, description, tags and `deprecated` of the use case. */
-export declare function metaOf(target: UseCaseTargetInfo, options: Options, verb: string): Pick<UseCaseCompilation, "name" | "description" | "tags" | "deprecated">;
+/** The name, description, tags, `deprecated`, route and access of the use case. */
+export declare function metaOf(target: UseCaseTargetInfo, options: Options, verb: string): Pick<UseCaseCompilation, "name" | "description" | "tags" | "deprecated" | "route" | "access">;
 /** The key of the response that holds the entity: the option `as`, `item` by default. */
 export declare function asOf(target: UseCaseTargetInfo, options: Options): string;
 /** The error of `kind` the options give, else `fallback`. */

package/dist/std/use-cases/shared.js

@@ -0,0 +1,232 @@
+import { blueprintBuilderOf } from "../../core/blueprint/blueprint.js";
+import { isDeclaredException } from "../../core/exception/exception.js";
+import { UseCaseEntityNotFound } from "../../core/use-case/exceptions.js";
+import { isPlain } from "../../core/use-case/steps/references.js";
+export const fields = blueprintBuilderOf();
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const capitalize = (key) => `${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+export function literal(value) {
+  if (typeof value === "string") {
+    return value.startsWith("$") ? { literal: value } : value;
+  }
+  if (Array.isArray(value))
+    return value.map(literal);
+  if (isPlain(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, literal(item)]));
+  }
+  return value;
+}
+export function checkOptions(target, options, allowed) {
+  const known = [...COMMON, ...allowed];
+  for (const key of Object.keys(options)) {
+    if (!known.includes(key)) {
+      target.unavailable(`it has no option "${key}" (options: ${known.join(", ")})`);
+    }
+  }
+}
+const COMMON = [
+  "name",
+  "description",
+  "tags",
+  "deprecated",
+  "errors",
+  "route",
+  "access"
+];
+export const HOOKS = ["before", "after", "dependencies", "throws"];
+export function metaOf(target, options, verb) {
+  const { name, description, tags, deprecated, route, access } = options;
+  if (name !== undefined && (typeof name !== "string" || name === "")) {
+    target.unavailable("the option name must be a non-empty string");
+  }
+  return {
+    name: name ?? `${verb}${target.entityName}`,
+    ...description === undefined ? {} : { description },
+    ...tags === undefined ? {} : { tags },
+    ...deprecated === undefined ? {} : { deprecated },
+    ...route === undefined ? {} : { route },
+    ...access === undefined ? {} : { access }
+  };
+}
+export function asOf(target, options) {
+  const { as = "item" } = options;
+  if (typeof as !== "string" || !IDENTIFIER.test(as)) {
+    target.unavailable("the option as must be an identifier");
+  }
+  return as;
+}
+export function errorOf(target, options, kind, fallback) {
+  const { errors } = options;
+  if (errors === undefined)
+    return fallback;
+  if (!isPlain(errors)) {
+    return target.unavailable("the option errors must be an object of exception classes");
+  }
+  const given = errors[kind];
+  if (given === undefined)
+    return fallback;
+  if (!isDeclaredException(given)) {
+    return target.unavailable(`errors.${kind} must be a class made by exceptionOf`);
+  }
+  return given;
+}
+export function keysOf(target, options, option) {
+  const given = options[option];
+  if (given === undefined)
+    return [];
+  if (!Array.isArray(given) || given.some((key) => typeof key !== "string")) {
+    return target.unavailable(`the option ${option} must be a list of keys`);
+  }
+  return given.map((key) => target.field(key));
+}
+export function valuesOf(target, options, option) {
+  const given = options[option];
+  if (given === undefined)
+    return {};
+  if (!isPlain(given)) {
+    return target.unavailable(`the option ${option} must be an object`);
+  }
+  for (const key of Object.keys(given)) {
+    if (target.field(key).identity) {
+      target.unavailable(`${option}.${key} is an identity key`);
+    }
+  }
+  return given;
+}
+export function ownerOf(target, options) {
+  const { owner } = options;
+  if (owner === undefined)
+    return;
+  if (!isPlain(owner) || typeof owner.context !== "string" || !IDENTIFIER.test(owner.context) || owner.key !== undefined && typeof owner.key !== "string") {
+    return target.unavailable("the option owner must be { key?, context }, context naming a context key");
+  }
+  const plan = target.field(owner.key ?? "ownerId");
+  if (plan.identity || plan.optional) {
+    target.unavailable(`owner.key "${plan.key}" must be a required key`);
+  }
+  if (plan.kind === "entity" && plan.related) {
+    return {
+      plan,
+      context: owner.context,
+      field: plan.related.blueprint.properties.id,
+      reference: `$item.${plan.key}.id`
+    };
+  }
+  if (plan.kind !== "property") {
+    target.unavailable(`owner.key "${plan.key}" must hold an id or an entity`);
+  }
+  return {
+    plan,
+    context: owner.context,
+    field: plan.field,
+    reference: `$item.${plan.key}`
+  };
+}
+export function contextOf(owner) {
+  return owner ? { context: fields(() => ({ [owner.context]: owner.field })) } : {};
+}
+export function loadSteps(owner, notFound) {
+  return [
+    { find: "repository.findById", args: ["$input.id"], as: "item" },
+    { ensure: "exists", value: "$item", error: notFound },
+    ...owner ? [
+      {
+        ensure: "equals",
+        value: owner.reference,
+        other: `$context.${owner.context}`,
+        error: notFound
+      }
+    ] : []
+  ];
+}
+export function hooksOf(target, options) {
+  const { before, after, dependencies = {}, throws = [] } = options;
+  for (const [key, hook] of [
+    ["before", before],
+    ["after", after]
+  ]) {
+    if (hook !== undefined && typeof hook !== "function") {
+      target.unavailable(`the option ${key} must be a function`);
+    }
+  }
+  if (!isPlain(dependencies) || Object.keys(dependencies).some((key) => !IDENTIFIER.test(key))) {
+    target.unavailable("the option dependencies must be an object of repositories, use cases or environments by name");
+  }
+  if (!Array.isArray(throws) || throws.some((error) => !isDeclaredException(error))) {
+    target.unavailable("the option throws must be a list of classes made by exceptionOf");
+  }
+  const input = before === undefined ? "$input" : "$prepared";
+  return {
+    input,
+    dependencies,
+    throws,
+    before: (entity) => before === undefined ? [] : [
+      {
+        run: "before",
+        fn: async (given, ...rest) => {
+          const { context, dependencies } = rest.at(-1);
+          const replaced = await before({
+            input: given,
+            ...entity === undefined ? {} : { entity: rest[0] },
+            dependencies,
+            context
+          });
+          return replaced === undefined ? given : replaced;
+        },
+        args: entity === undefined ? ["$input"] : ["$input", entity],
+        as: "prepared"
+      }
+    ],
+    after: (entity) => after === undefined ? [] : [
+      {
+        run: "after",
+        fn: async (written, given, { context, dependencies }) => {
+          await after({
+            entity: written,
+            input: given,
+            dependencies,
+            context
+          });
+        },
+        args: [entity, input]
+      }
+    ]
+  };
+}
+export function joinDependencies(target, made, hooks) {
+  for (const key of Object.keys(hooks.dependencies)) {
+    if (Object.hasOwn(made, key)) {
+      target.unavailable(`dependencies.${key} is a name the use case gives its own dependency`);
+    }
+  }
+  return { ...made, ...hooks.dependencies };
+}
+export const idOf = (target) => target.field("id").field;
+export const distinct = (...errors) => [...new Set(errors)];
+export function entityUseCase(target, options, verb, allowed, steps, hooks = false) {
+  checkOptions(target, options, [
+    "as",
+    "owner",
+    ...allowed,
+    ...hooks ? HOOKS : []
+  ]);
+  const owner = ownerOf(target, options);
+  const notFound = errorOf(target, options, "notFound", UseCaseEntityNotFound);
+  const hooked = hooksOf(target, options);
+  const body = steps({ owner, input: hooked.input });
+  return {
+    ...metaOf(target, options, verb),
+    blueprint: fields(() => ({ id: idOf(target) })),
+    response: fields(() => ({ [asOf(target, options)]: target.entity })),
+    ...contextOf(owner),
+    dependencies: joinDependencies(target, { repository: target.repository }, hooked),
+    errors: distinct(notFound, ...hooked.throws),
+    steps: [
+      ...loadSteps(owner, notFound),
+      ...hooked.before("$item"),
+      ...body.steps,
+      ...hooked.after(body.result),
+      { return: { [asOf(target, options)]: body.result } }
+    ]
+  };
+}