@afora/core 0.0.9 → 0.0.12

package/dist/core/openapi/openapi.js

@@ -0,0 +1,132 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import { isRecordClass, recordFieldOf } from "../blueprint/record-field.js";
+import { isBlueprintVariant } from "../blueprint/variant.js";
+import { identityKeysOf } from "../entity/abstract-entity.js";
+import { isEntityClass } from "../entity/entity.js";
+import { isProperty } from "../property/is-property.js";
+import { rawTypeOf } from "../schema/schema.js";
+import { InvalidOpenAPIModel } from "./exceptions.js";
+const NO_MARKS = { writeOnly: [], readOnly: [] };
+function isField(value) {
+  return isProperty(value) || isBlueprint(value) || isBlueprintList(value) || isBlueprintVariant(value) || recordFieldOf(value) !== undefined;
+}
+function isOptional(field) {
+  if (isProperty(field))
+    return field.type.optional === true;
+  if (isBlueprint(field) || isBlueprintList(field) || isBlueprintVariant(field)) {
+    return field.optional;
+  }
+  return recordFieldOf(field)?.optional ?? false;
+}
+export function plainOf(value, nested = false) {
+  if (Array.isArray(value))
+    return value.map((item) => plainOf(item, true));
+  if (typeof value !== "object" || value === null)
+    return value;
+  const id = value.$id;
+  if (nested && typeof id === "string")
+    return { $ref: id };
+  const plain = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (!key.startsWith("~"))
+      plain[key] = plainOf(item, true);
+  }
+  return plain;
+}
+function objectOf(properties, scope, marks) {
+  const shape = {};
+  const required = [];
+  for (const [key, field] of Object.entries(properties)) {
+    const schema = schemaOf(field, scope);
+    if (marks.readOnly.includes(key))
+      schema.readOnly = true;
+    if (marks.writeOnly.includes(key))
+      schema.writeOnly = true;
+    shape[key] = schema;
+    if (!isOptional(field))
+      required.push(key);
+  }
+  return {
+    type: "object",
+    properties: shape,
+    ...required.length > 0 ? { required } : {},
+    additionalProperties: false
+  };
+}
+function recordSchemaOf(record, scope) {
+  const { sensitive = [] } = record.options ?? {};
+  return objectOf(record.blueprint.properties, scope, {
+    writeOnly: sensitive,
+    readOnly: isEntityClass(record) ? identityKeysOf(record) : []
+  });
+}
+function schemaOf(field, scope) {
+  if (isBlueprintList(field)) {
+    const { item, minItems, maxItems } = field;
+    return {
+      type: "array",
+      items: schemaOf(item, scope),
+      ...minItems === undefined ? {} : { minItems },
+      ...maxItems === undefined ? {} : { maxItems }
+    };
+  }
+  if (isBlueprint(field))
+    return objectOf(field.properties, scope, NO_MARKS);
+  if (isBlueprintVariant(field)) {
+    const variants = field.variants;
+    return {
+      oneOf: Object.entries(variants).map(([tag, variant]) => {
+        const object = isRecordClass(variant) ? recordSchemaOf(variant, scope) : objectOf(variant.properties, scope, NO_MARKS);
+        return {
+          ...object,
+          properties: { [field.key]: { const: tag }, ...object.properties },
+          required: [field.key, ...object.required ?? []]
+        };
+      }),
+      discriminator: { propertyName: field.key }
+    };
+  }
+  const record = recordFieldOf(field);
+  if (record) {
+    const name = scope.names.get(record.record);
+    return name === undefined ? recordSchemaOf(record.record, scope) : { $ref: `${scope.prefix}${name}` };
+  }
+  if (!isProperty(field)) {
+    throw new InvalidOpenAPIModel({
+      source: "openapi",
+      details: { name: String(field) }
+    });
+  }
+  const schema = plainOf(rawTypeOf(field.type.schema));
+  if (field.type.sensitive)
+    schema.writeOnly = true;
+  return schema;
+}
+export function toOpenAPI(modelOrModels, { refPrefix = "#/components/schemas/" } = {}) {
+  if (isField(modelOrModels)) {
+    return schemaOf(modelOrModels, { names: new Map, prefix: refPrefix });
+  }
+  if (typeof modelOrModels !== "object" || modelOrModels === null) {
+    throw new InvalidOpenAPIModel({
+      source: "openapi",
+      details: { name: String(modelOrModels) }
+    });
+  }
+  const names = new Map;
+  for (const [name, model] of Object.entries(modelOrModels)) {
+    if (!isField(model)) {
+      throw new InvalidOpenAPIModel({ source: "openapi", details: { name } });
+    }
+    const record = recordFieldOf(model);
+    if (record && !names.has(record.record))
+      names.set(record.record, name);
+  }
+  const scope = { names, prefix: refPrefix };
+  const schemas = {};
+  for (const [name, model] of Object.entries(modelOrModels)) {
+    const record = recordFieldOf(model);
+    schemas[name] = record && names.get(record.record) === name ? recordSchemaOf(record.record, scope) : schemaOf(model, scope);
+  }
+  return { schemas };
+}

package/dist/core/openapi/types/openapi.interface.d.ts

@@ -28,10 +28,16 @@ export interface OpenAPIComponents<Name extends PropertyKey = string> {
         readonly [Key in Name]: OpenAPISchema;
     };
 }
+/**
+ * What `toOpenAPI` takes after the models: how a record named among them is
+ * referenced.
+ */
 export interface OpenAPIOptions {
     /**
      * Where a record named among the models is referenced from: `$ref` is this
-     * prefix and its name. `"#/components/schemas/"` by default.
+     * prefix and its name.
+     *
+     * @default "#/components/schemas/"
      */
     readonly refPrefix?: string;
 }

package/dist/core/output/access.js

@@ -0,0 +1,66 @@
+import { isPublicAccess } from "../use-case/access.js";
+import { Forbidden, InvalidOutputStage, Unauthenticated } from "./exceptions.js";
+function readerOf(path) {
+  if (path === "subject")
+    return (principal) => principal.subject;
+  if (path === "scopes")
+    return (principal) => [...principal.scopes];
+  const claim = path.slice("claims.".length);
+  return (principal) => principal.claims && Object.hasOwn(principal.claims, claim) ? principal.claims[claim] : undefined;
+}
+export function accessGuardOf(id, access, context) {
+  if (isPublicAccess(access)) {
+    return (_input, options) => options === undefined ? undefined : { context: options.context };
+  }
+  const scopes = access.scopes ?? [];
+  const owner = access.owner;
+  const ownerOf = owner ? readerOf(owner.claim === undefined ? "subject" : `claims.${owner.claim}`) : undefined;
+  const fills = Object.entries(access.context ?? {}).map(([key, path]) => [key, readerOf(path)]);
+  for (const [key] of fills) {
+    if (!context || !Object.hasOwn(context.properties, key)) {
+      throw new InvalidOutputStage({
+        source: id,
+        details: {
+          reason: `The access of ${id} fills the context key "${key}", which the context of the operation does not declare.`
+        }
+      });
+    }
+  }
+  return (input, options) => {
+    const principal = options?.principal;
+    if (principal === undefined || principal === null || typeof principal.subject !== "string" || !Array.isArray(principal.scopes)) {
+      throw new Unauthenticated({ source: id });
+    }
+    if (scopes.length > 0) {
+      const missing = scopes.filter((scope) => !principal.scopes.includes(scope));
+      if (missing.length > 0) {
+        throw new Forbidden({
+          source: id,
+          details: { reason: "scope", scopes: missing }
+        });
+      }
+    }
+    if (owner && ownerOf) {
+      const expected = ownerOf(principal);
+      const given = typeof input === "object" && input !== null ? input[owner.input] : undefined;
+      if (given === undefined || given === null || expected === undefined || expected === null || String(given) !== String(expected)) {
+        throw new Forbidden({ source: id, details: { reason: "owner" } });
+      }
+    }
+    if (fills.length === 0) {
+      return options?.context === undefined ? undefined : { context: options.context };
+    }
+    const given = options?.context;
+    const filled = {
+      ...typeof given === "object" && given !== null ? given : {}
+    };
+    for (const [key, read] of fills) {
+      const value = read(principal);
+      if (value === undefined)
+        delete filled[key];
+      else
+        filled[key] = value;
+    }
+    return { context: filled };
+  };
+}

package/dist/core/output/coerce.js

@@ -0,0 +1,38 @@
+import { toOpenAPI } from "../openapi/openapi.js";
+const scalarTypes = new WeakMap;
+function scalarTypesOf(blueprint) {
+  let types = scalarTypes.get(blueprint);
+  if (!types) {
+    const schema = toOpenAPI(blueprint);
+    const found = {};
+    for (const [key, property] of Object.entries(schema.properties ?? {})) {
+      found[key] = [property.type ?? []].flat();
+    }
+    types = Object.freeze(found);
+    scalarTypes.set(blueprint, types);
+  }
+  return types;
+}
+function coerce(text, types) {
+  if (!types || types.includes("string"))
+    return text;
+  const trimmed = text.trim();
+  if (types.includes("boolean") && (trimmed === "true" || trimmed === "false")) {
+    return trimmed === "true";
+  }
+  if (types.includes("integer") || types.includes("number")) {
+    const number = trimmed === "" ? Number.NaN : Number(trimmed);
+    if (Number.isFinite(number))
+      return number;
+  }
+  return text;
+}
+export function coerceTextValues(blueprint, texts) {
+  const types = scalarTypesOf(blueprint);
+  const out = {};
+  for (const [key, value] of Object.entries(texts)) {
+    if (value !== undefined)
+      out[key] = coerce(value, types[key]);
+  }
+  return out;
+}

package/dist/core/output/exceptions.js

@@ -0,0 +1,22 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const InvalidOutputStage = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "InvalidOutputStage",
+  message: ({ reason }) => reason
+});
+export const DuplicateOperation = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "DuplicateOperation",
+  message: ({ id }) => `The operation "${id}" is declared twice.`
+});
+export const Unauthenticated = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "Unauthenticated",
+  message: "Authentication is required."
+});
+export const Forbidden = exceptionOf({
+  layer: ExceptionLayers.Output,
+  name: "Forbidden",
+  message: (_details) => "The caller may not do this."
+});

package/dist/{index-y280ew0k.js → core/output/http.js}

@@ -1,61 +1,17 @@
+import { jwtOf, jwtOptionsIssue } from "../auth/jwt.js";
+import { Exception } from "../exception/exception.js";
+import { HEADER_NAME } from "../use-case/route.js";
+import { coerceTextValues } from "./coerce.js";
+import { InvalidOutputStage } from "./exceptions.js";
 import {
-  statusOf2,
-  PROBLEM_MEDIA_TYPE2,
-  problemOf2,
-  outputValueOf2,
-  ROUTE_OPTION_KEYS2,
-  routeOptionsIssue2,
-  requestIdHeaderOf2,
-  operationRoutes2,
-  openapi2
-} from "./index-hg1z2s2v.js";
-import {
-  Exception2,
-  toOpenAPI2,
-  HEADER_NAME,
-  InvalidOutputStage2,
-  jwtOptionsIssue,
-  jwtOf2
-} from "./index-xegv6a1p.js";
-// src/core/output/coerce.ts
-var scalarTypes = new WeakMap;
-function scalarTypesOf(blueprint) {
-  let types = scalarTypes.get(blueprint);
-  if (!types) {
-    const schema = toOpenAPI2(blueprint);
-    const found = {};
-    for (const [key, property] of Object.entries(schema.properties ?? {})) {
-      found[key] = [property.type ?? []].flat();
-    }
-    types = Object.freeze(found);
-    scalarTypes.set(blueprint, types);
-  }
-  return types;
-}
-function coerce(text, types) {
-  if (!types || types.includes("string"))
-    return text;
-  const trimmed = text.trim();
-  if (types.includes("boolean") && (trimmed === "true" || trimmed === "false")) {
-    return trimmed === "true";
-  }
-  if (types.includes("integer") || types.includes("number")) {
-    const number = trimmed === "" ? Number.NaN : Number(trimmed);
-    if (Number.isFinite(number))
-      return number;
-  }
-  return text;
-}
-function coerceTextValues2(blueprint, texts) {
-  const types = scalarTypesOf(blueprint);
-  const out = {};
-  for (const [key, value] of Object.entries(texts)) {
-    if (value !== undefined)
-      out[key] = coerce(value, types[key]);
-  }
-  return out;
-}
-// src/core/output/http.ts
+  openapi,
+  operationRoutes,
+  ROUTE_OPTION_KEYS,
+  requestIdHeaderOf,
+  routeOptionsIssue
+} from "./openapi-sink.js";
+import { outputValueOf, PROBLEM_MEDIA_TYPE, problemOf } from "./problem.js";
+import { statusOf } from "./status.js";
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -66,16 +22,16 @@ function onlyKeys(value, allowed, where) {
   }
   return;
 }
-var HTTP_OPTION_KEYS2 = [
-  ...ROUTE_OPTION_KEYS2,
+export const HTTP_OPTION_KEYS = [
+  ...ROUTE_OPTION_KEYS,
   "docs",
   "debug",
   "context",
   "auth"
 ];
-function httpOptionsIssue2(options, where) {
+export function httpOptionsIssue(options, where) {
   const given = options;
-  const routing = routeOptionsIssue2(options, where);
+  const routing = routeOptionsIssue(options, where);
   if (routing)
     return routing;
   if (given.debug !== undefined && typeof given.debug !== "boolean") {
@@ -109,7 +65,7 @@ function httpOptionsIssue2(options, where) {
       return `Expected ${where}.docs.path to be a path such as "/openapi.json".`;
     }
     try {
-      openapi2({
+      openapi({
         info: docs.info,
         ...docs.servers ? { servers: docs.servers } : {}
       });
@@ -151,9 +107,9 @@ function httpOptionsIssue2(options, where) {
   }
   return;
 }
-var REQUEST_ID = /^[\x21-\x7e]{1,200}$/;
-var JSON_TYPE = "application/json";
-var NO_COOKIES = Object.freeze([]);
+const REQUEST_ID = /^[\x21-\x7e]{1,200}$/;
+const JSON_TYPE = "application/json";
+const NO_COOKIES = Object.freeze([]);
 function cookiesOf(header) {
   const cookies = new Map;
   if (!header)
@@ -190,28 +146,28 @@ function cookieWriterOf(cookie) {
   const lasting = cookie.maxAge === undefined ? "" : `; Max-Age=${cookie.maxAge}`;
   return (value) => value === "" ? `${cookie.name}=; ${attributes}; Max-Age=0` : `${cookie.name}=${encodeURIComponent(value)}; ${attributes}${lasting}`;
 }
-function compileRoutes2(operations, options, context, settings) {
+export function compileRoutes(operations, options, context, settings) {
   const { source } = settings;
   const { output } = context;
   let authenticator = settings.authenticator;
   if (!authenticator && options.auth) {
     const { header, cookie, ...jwt } = options.auth.jwt;
-    authenticator = jwtOf2(jwt).authenticator({
+    authenticator = jwtOf(jwt).authenticator({
       ...header === undefined ? {} : { header },
       ...cookie === undefined ? {} : { cookie }
     });
   }
-  const routes = operationRoutes2(operations, options, source);
+  const routes = operationRoutes(operations, options, source);
   const debug = options.debug === true;
   const contextHeaders = options.context?.headers ?? {};
   const contextVariables = options.context?.variables ?? {};
-  const requestIdHeader = requestIdHeaderOf2(options);
+  const requestIdHeader = requestIdHeaderOf(options);
   const idOf = (request) => {
     const sent = request?.header(requestIdHeader);
     return sent !== undefined && REQUEST_ID.test(sent) ? sent : crypto.randomUUID();
   };
   const headersOf = (headers, request) => requestIdHeader === undefined ? headers : { ...headers, [requestIdHeader]: idOf(request) };
-  const problemHeaders = Object.freeze({ "content-type": PROBLEM_MEDIA_TYPE2 });
+  const problemHeaders = Object.freeze({ "content-type": PROBLEM_MEDIA_TYPE });
   const problem = (body, status, request) => ({
     status,
     headers: headersOf(problemHeaders, request),
@@ -219,8 +175,8 @@ function compileRoutes2(operations, options, context, settings) {
     body: JSON.stringify(body)
   });
   const fail = (error, operation, request, fallback) => {
-    const status = fallback !== undefined && !(error instanceof Exception2 && Object.hasOwn(output.statuses, error.name)) ? fallback : statusOf2(error, operation, output.statuses);
-    return problem(problemOf2(error, { status, debug }), status, request);
+    const status = fallback !== undefined && !(error instanceof Exception && Object.hasOwn(output.statuses, error.name)) ? fallback : statusOf(error, operation, output.statuses);
+    return problem(problemOf(error, { status, debug }), status, request);
   };
   const failure = (error, given) => fail(error, given?.operation, given?.request, given?.status);
   const compiled = operations.map((operation) => {
@@ -268,7 +224,7 @@ function compileRoutes2(operations, options, context, settings) {
             }, 400, request);
           }
         } else {
-          input = coerceTextValues2(operation.input, request.query());
+          input = coerceTextValues(operation.input, request.query());
         }
         if (placed && isObject(input)) {
           const texts = {};
@@ -287,7 +243,7 @@ function compileRoutes2(operations, options, context, settings) {
           }
           for (const name of parameters)
             texts[name] = request.param(name);
-          input = { ...input, ...coerceTextValues2(operation.input, texts) };
+          input = { ...input, ...coerceTextValues(operation.input, texts) };
         }
         let call;
         if (hasContext) {
@@ -295,7 +251,7 @@ function compileRoutes2(operations, options, context, settings) {
           for (const [key, name] of contextHeaderKeys) {
             raw[key] = request.header(name);
           }
-          const values = coerceTextValues2(operation.context, raw);
+          const values = coerceTextValues(operation.context, raw);
           for (const [key, name] of contextVariableKeys) {
             const value = request.variable?.(name);
             if (value !== undefined)
@@ -313,7 +269,7 @@ function compileRoutes2(operations, options, context, settings) {
             body: status === 204 ? null : JSON.stringify(response) ?? "null"
           };
         }
-        const value = outputValueOf2(response);
+        const value = outputValueOf(response);
         const sent = [];
         if (isObject(value)) {
           for (const [key, write] of setCookies) {
@@ -340,7 +296,7 @@ function compileRoutes2(operations, options, context, settings) {
   if (options.docs) {
     const { path, info, servers } = options.docs;
     if (compiled.some((route) => route.method === "get" && route.path === path)) {
-      throw new InvalidOutputStage2({
+      throw new InvalidOutputStage({
         source,
         details: {
           reason: `${source}.docs.path "${path}" collides with a GET operation route.`
@@ -348,7 +304,7 @@ function compileRoutes2(operations, options, context, settings) {
       });
     }
     const routing = {};
-    for (const key of ROUTE_OPTION_KEYS2) {
+    for (const key of ROUTE_OPTION_KEYS) {
       if (options[key] !== undefined)
         routing[key] = options[key];
     }
@@ -364,7 +320,7 @@ function compileRoutes2(operations, options, context, settings) {
         }
       };
     }
-    const document = openapi2({
+    const document = openapi({
       info,
       ...servers ? { servers } : {},
       ...routing
@@ -393,4 +349,3 @@ function compileRoutes2(operations, options, context, settings) {
     failure
   });
 }
-export { coerceTextValues2, HTTP_OPTION_KEYS2, httpOptionsIssue2, compileRoutes2 };

package/dist/core/output/openapi-sink.d.ts

@@ -45,7 +45,11 @@ export interface SecurityRequirement {
  * sinks that serve HTTP, so the served routes and the document agree.
  */
 export interface RouteOptions {
-    /** Prefix of every path, e.g. `"/api"`. Empty by default. */
+    /**
+     * Prefix of every path, e.g. `"/api"`.
+     *
+     * @default ""
+     */
     readonly basePath?: string;
     /**
      * Method, path and success status by operation id, e.g.
@@ -56,7 +60,11 @@ export interface RouteOptions {
         readonly [operationId: string]: {
             readonly method?: OpenAPIMethod;
             readonly path?: string;
-            /** `200` by default. */
+            /**
+             * The status of a successful response.
+             *
+             * @default 200
+             */
             readonly status?: RouteStatus;
         };
     };