@occultist/occultist 0.0.1

package/lib/utils/getPropertyValueSpecifications.ts

@@ -0,0 +1,76 @@
+import type { OrArray, JSONValue } from "../jsonld.js";
+import type { ActionSpec, PropertySpec, ResponseInputSpec, SpecValue, ActionOption } from "../actions/spec.js";
+import { isNil } from "./isNil.js";
+import { isObject } from "./isObject.js";
+
+
+// deno-lint-ignore no-explicit-any
+export async function getPropertyValueSpecifications(spec: ActionSpec<any>) {
+  async function splitSpecAndValue(
+    propertySpec: PropertySpec,
+  ): Promise<
+    [ResponseInputSpec, SpecValue | OrArray<ActionOption<JSONValue>> | null]
+  > {
+    let options: OrArray<ActionOption<JSONValue>> | null = null;
+
+    const specValue: SpecValue = {};
+    const inputSpec: ResponseInputSpec = {
+      '@type': 'https://schema.org/PropertyValueSpecification',
+      defaultValue: propertySpec.defaultValue,
+      maxValue: propertySpec.maxValue,
+      minValue: propertySpec.minValue,
+      readonlyValue: propertySpec.readonlyValue,
+      stepValue: propertySpec.stepValue,
+      valueName: propertySpec.valueName,
+      valueRequired: propertySpec.valueRequired,
+      multipleValues: propertySpec.multipleValues,
+      valueMinLength: propertySpec.valueMinLength,
+      valueMaxLength: propertySpec.valueMaxLength,
+      valuePatern: propertySpec.valuePattern,
+    };
+
+    if (typeof propertySpec.options === 'function') {
+      options = await propertySpec.options();
+    } else if (!isNil(propertySpec.options)) {
+      options = propertySpec.options;
+    }
+
+    if (!isObject(propertySpec.properties)) {
+      return [inputSpec, options];
+    }
+
+    for (
+      const [term, childPropertySpec] of Object.entries(
+        propertySpec.properties,
+      )
+    ) {
+      const [childInputSpec, childSpecValue] = await splitSpecAndValue(
+        childPropertySpec,
+      );
+
+      specValue[`${term}-input`] = childInputSpec;
+
+      if (childSpecValue != null) {
+        specValue[term] = childSpecValue;
+      }
+    }
+
+    return [inputSpec, specValue];
+  }
+
+  const specValue: SpecValue = {};
+
+  for (const [term, propertySpec] of Object.entries(spec)) {
+    const [childInputSpec, childSpecValue] = await splitSpecAndValue(
+      propertySpec,
+    );
+
+    specValue[`${term}-input`] = childInputSpec;
+
+    if (childSpecValue != null) {
+      specValue[term] = childSpecValue;
+    }
+  }
+
+  return specValue;
+}

package/lib/utils/getRequestBodyValues.ts

@@ -0,0 +1,155 @@
+import { ProblemDetailsError } from "../errors.js";
+import type { JSONValue, ContextDefinition, JSONObject } from "../jsonld.js";
+import type { ContextState, ActionSpec, PropertySpec } from "../actions/spec.js";
+import jsonld from 'jsonld';
+import type { ImplementedAction } from "../actions/types.js";
+
+
+// export type BodyValue = Record<string, FileInput | FileInput[] | JSONValue>;
+export type BodyValue = Record<string, JSONValue>;
+
+
+export type RequestBodyResult = {
+  bodyValues: BodyValue;
+};
+
+export async function getRequestBodyValues<
+  State extends ContextState = ContextState,
+  Spec extends ActionSpec<ContextState> = ActionSpec<ContextState>,
+>({
+  req,
+  action,
+}: {
+  req: Request,
+  action: ImplementedAction<State, Spec>,
+}): Promise<RequestBodyResult> {
+  let bodyValues: BodyValue = {};
+  const contentType = req.headers.get('content-type');
+  const mappedTypes: Record<string, {
+    term: string;
+    propertySpec: PropertySpec;
+  }> = Object.entries<PropertySpec>(action.spec)
+    .reduce((acc, [term, propertySpec]) => {
+      return {
+        ...acc,
+        [propertySpec.typeDef.term]: {
+          term,
+          propertySpec,
+        },
+        [propertySpec.type || propertySpec.typeDef?.type]: {
+          term,
+          propertySpec,
+        },
+      };
+    }, {});
+
+  if (contentType?.startsWith('multipart/form-data')) {
+    // multipart should be sent using expanded types which get normalized
+    // into the compact terms for each type.
+    // otherwise json requests would need to also need to use
+    // expanded terms.
+    const formData = await req.formData();
+
+    for (const [name, part] of formData.entries()) {
+      if (typeof name !== 'string') {
+        throw new ProblemDetailsError(400, {
+          title: 'Unnamed parameter in request multipart body',
+        });
+      }
+
+      let term: string | undefined;
+      let propertySpec: PropertySpec | undefined;
+
+      if (typeof part !== 'string' && (part.type && !part.type.startsWith('text/plain'))) {
+        term = mappedTypes[name].term;
+        propertySpec = mappedTypes[name].propertySpec;
+
+        if (!term || !propertySpec) {
+          continue;
+        }
+
+        if (propertySpec.dataType !== 'file') {
+          throw new ProblemDetailsError(400, {
+            title: `Unexpected content '${name}' in request multipart body`,
+          });
+        }
+
+        //bodyValues[term] = part;
+        bodyValues[term] = null;
+        continue;
+      }
+
+      if (typeof part === 'string' || part.type === 'text/plain' || part.type == null) {
+        term = mappedTypes[name].term;
+        propertySpec = mappedTypes[name].propertySpec;
+      } else if (part.name) {
+        term = mappedTypes[name].term;
+        propertySpec = mappedTypes[name].propertySpec;
+      } else {
+        throw new ProblemDetailsError(400, {
+          title: `Unexpected content '${name}' in request multipart body`,
+        });
+      }
+
+      if (!term || !propertySpec) {
+        continue;
+      }
+
+      const textValue = typeof part === 'string' ? part : await part.text();
+
+      if (!textValue) {
+        continue;
+      }
+
+      if (propertySpec.dataType === 'number' && /\d+(\.\d+)?/.test(textValue)) {
+        bodyValues[term] = Number(textValue);
+      } else if (propertySpec.dataType === 'boolean') {
+        bodyValues[term] = textValue === 'true';
+      } else {
+        bodyValues[term] = textValue;
+      }
+    }
+  } else if (contentType?.startsWith('application/json')) {
+    try {
+      bodyValues = await req.json();
+    } catch {
+      throw new ProblemDetailsError(400, {
+        title: 'Failed to parse JSON body',
+      });
+    }
+  } else if (contentType?.startsWith('application/ld+json')) {
+    let source: JSONValue;
+    let expanded: jsonld.JsonLdDocument;
+    let compacted: jsonld.NodeObject | undefined;
+
+    try {
+      source = await req.json();
+    } catch {
+      throw new ProblemDetailsError(400, {
+        title: 'Failed to parse JSON body',
+      });
+    }
+
+    try {
+      expanded = await jsonld.expand(source as jsonld.JsonLdDocument);
+    } catch {
+      throw new ProblemDetailsError(400, {
+        title: 'Failed to expand JSON-LD body',
+      });
+    }
+
+    try {
+      compacted = await jsonld.compact(expanded, action.context as ContextDefinition)
+    } catch {
+      throw new ProblemDetailsError(400, {
+        title: 'Failed to compact JSON-LD body',
+      });
+    }
+
+    delete compacted['@context'];
+
+    bodyValues = compacted as JSONObject;
+  }
+
+  return { bodyValues };
+}

package/lib/utils/getRequestIRIValues.ts

@@ -0,0 +1,201 @@
+import type { ImplementedAction } from "../actions/types.js";
+import { ProblemDetailsError } from "../errors.js";
+import type { ActionSpec, ContextState, FileSingleSpec, FileMultiSpec, BooleanSingleSpec, BooleanMultiSpec, NumberSingleSpec, NumberMultiSpec, StringSingleSpec, StringMultiSpec, ParsedIRIValues, PropertySpec } from "../actions/spec.js";
+import { getParamLocation } from "./getParamLocation.js";
+
+
+export type IRIValue<
+  Spec extends ActionSpec<ContextState> = ActionSpec<ContextState>,
+> = {
+  [Term in keyof Spec]: (
+    Spec[Term] extends FileSingleSpec | FileMultiSpec ? never
+      : Spec[Term]['valueName'] extends string ? (
+          Spec[Term] extends BooleanSingleSpec ? boolean
+            : Spec[Term] extends BooleanMultiSpec ? boolean[]
+            : Spec[Term] extends NumberSingleSpec ? number
+            : Spec[Term] extends NumberMultiSpec ? number[]
+            : Spec[Term] extends StringSingleSpec ? string
+            : Spec[Term] extends StringMultiSpec ? string[]
+            : never
+        )
+      : never
+  );
+};
+
+export type RequestIRIResult<
+  Spec extends ActionSpec<ContextState> = ActionSpec<ContextState>,
+> = {
+  pathValues: ParsedIRIValues;
+  queryValues: ParsedIRIValues;
+  iriValues: IRIValue<Spec>;
+};
+
+export function getRequestIRIValues<
+  State extends ContextState = ContextState,
+  Spec extends ActionSpec<ContextState> = ActionSpec<ContextState>,
+>({
+  iri,
+  action,
+}: {
+  iri: string;
+  action: ImplementedAction<State, Spec>;
+}): RequestIRIResult<Spec> {
+  const pathValues: ParsedIRIValues = {};
+  const queryValues: ParsedIRIValues = {};
+  // deno-lint-ignore no-explicit-any
+  const iriValues = {} as IRIValue<any>;
+  const urlPatternResult = action.pattern.exec(iri);
+  const pathParams = urlPatternResult?.pathname.groups || {};
+  const searchParams = new URL(iri).searchParams;
+
+  const valueNames = Object.values<PropertySpec>(action.spec)
+    .filter((specItem) => typeof specItem.valueName === 'string')
+    .map((specItem) => specItem.valueName);
+
+  //if (action.strict) {
+    for (const valueName of searchParams.keys()) {
+      if (!valueNames.includes(valueName)) {
+        throw new ProblemDetailsError(400, {
+          title: `Unexpected value "${valueName}"`,
+        });
+      }
+    }
+  //}
+
+  for (
+    const [term, specItem] of Object.entries(
+      action.spec as unknown as Record<string, PropertySpec>,
+    )
+  ) {
+    if (typeof specItem.valueName !== 'string') {
+      continue;
+    }
+
+    let value: string | string[] | undefined | null;
+    const valueName = specItem.valueName;
+    const multipleValues = Boolean(specItem.multipleValues);
+    const paramLocation = getParamLocation(valueName, action.pattern);
+
+    if (paramLocation === 'path') {
+      value = pathParams[valueName];
+    } else {
+      value = searchParams.getAll(valueName);
+    }
+
+    if (value === null) {
+      value = undefined;
+    }
+
+    if (!multipleValues && Array.isArray(value) && value.length > 1) {
+      throw new ProblemDetailsError(400, {
+        title: `Invalid request`,
+        errors: [{
+          name: term,
+          pointer: `#${term}`,
+          reason: `Received array when expecting single value`,
+        }],
+      });
+    }
+
+    if (multipleValues && typeof value === 'string') {
+      value = [value];
+    } else if (!multipleValues && Array.isArray(value)) {
+      value = value[0];
+    }
+
+    if (typeof value === 'undefined') {
+      continue;
+    } else if (!specItem.valueRequired && Array.isArray(value) && value.length === 0) {
+      continue;
+    }
+
+    if (specItem.dataType === 'boolean' && typeof value === 'string') {
+      iriValues[term] = parseBoolean({
+        term,
+        value,
+        pointer: `#${term}`,
+      });
+    } else if (specItem.dataType === 'boolean' && Array.isArray(value)) {
+      iriValues[term] = value.map((value, index) => parseBoolean({
+        term,
+        value,
+        pointer: `#${term}[${index}]`,
+      }));
+    } else if (specItem.dataType === 'number' && typeof value === 'string') {
+      iriValues[term] = parseNumber({
+        term,
+        value,
+        pointer: `#${term}`,
+      });
+    } else if (specItem.dataType === 'number' && Array.isArray(value)) {
+      iriValues[term] = value.map((value, index) => parseNumber({
+        term,
+        value,
+        pointer: `#${term}[${index}]`,
+      }));
+    } else {
+      // string values don't require parsing
+      iriValues[term] = value;
+    }
+
+    if (paramLocation === 'path') {
+      pathValues[term] = iriValues[term];
+    } else {
+      queryValues[term] = iriValues[term];
+    }
+  }
+
+  return {
+    pathValues,
+    queryValues,
+    iriValues,
+  };
+}
+
+function parseBoolean({
+  term,
+  value,
+  pointer,
+}: {
+  term: string;
+  value: string;
+  pointer: string;
+}): boolean {
+  if (!['', 'true', 'false'].includes(value)) {
+    throw new ProblemDetailsError(400, {
+      title: `Invalid request`,
+      errors: [{
+        name: term,
+        pointer,
+        reason: `Boolean values must be "", "true" or "false"`,
+      }],
+    })
+  }
+
+  return value === '' || value === 'true';
+}
+
+function parseNumber({
+  term,
+  value,
+  pointer,
+}: {
+  term: string;
+  value: string;
+  pointer: string;
+}): number {
+  const numberValue = Number(value);
+
+  if (isNaN(numberValue) || !Number.isFinite(numberValue)) {
+    throw new ProblemDetailsError(400, {
+      title: `Invalid request`,
+      errors: [{
+        name: term,
+        pointer,
+        reason: `Numeric values must valid numbers and finite`,
+      }],
+    });
+  }
+
+  return numberValue;
+}

package/lib/utils/isBodyInit.ts

@@ -0,0 +1,22 @@
+
+export function isBodyInit(value: unknown): value is BodyInit {
+  return value instanceof ReadableStream ||
+    value instanceof Blob ||
+    value instanceof DataView ||
+    value instanceof ArrayBuffer ||
+    value instanceof Int8Array ||
+    value instanceof Uint8Array ||
+    value instanceof Uint8ClampedArray ||
+    value instanceof Int16Array ||
+    value instanceof Uint16Array ||
+    value instanceof Int32Array ||
+    value instanceof Uint32Array ||
+    value instanceof Float16Array ||
+    value instanceof Float32Array ||
+    value instanceof Float64Array ||
+    value instanceof BigInt64Array ||
+    value instanceof BigUint64Array ||
+    value instanceof FormData ||
+    value instanceof URLSearchParams ||
+    typeof value === 'string';
+}

package/lib/utils/isNil.ts

@@ -0,0 +1,4 @@
+// deno-lint-ignore no-explicit-any
+export function isNil(value: any): value is null | undefined {
+  return typeof value === 'undefined' || value === null;
+}

package/lib/utils/isObject.ts

@@ -0,0 +1,8 @@
+type ObjectValue = Record<string | number | symbol, unknown>;
+
+/**
+ * Returns true if the input value is a plain Javascript object.
+ */
+export function isObject<T extends ObjectValue = ObjectValue>(value: unknown): value is T {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/lib/utils/isPopulatedObject.ts

@@ -0,0 +1,9 @@
+import { isObject } from './isObject.js';
+
+/**
+ * Returns true if the input value is a plain Javascript object with
+ * at least one member.
+ */
+export function isPopulatedObject<ChildType>(value: unknown): value is Record<string, ChildType> {
+  return isObject(value) && Object.keys(value).length > 0;
+}

package/lib/utils/isPopulatedString.ts

@@ -0,0 +1,4 @@
+// deno-lint-ignore no-explicit-any
+export function isPopulatedString(value: any): value is string {
+  return typeof value === 'string' && value.length !== 0;
+}

package/lib/utils/joinPaths.ts

@@ -0,0 +1,36 @@
+export function joinPaths(...paths: Array<string | number>): string {
+  let fullPath: string = '';
+
+  if (paths[0] == null || paths[0] == '') {
+    throw new Error(
+      'The first path must be a populated string when joining paths',
+    );
+  }
+
+  for (const pathSrc of paths) {
+    let path: string | null = null;
+
+    if (typeof pathSrc === 'number') {
+      path = `${pathSrc}`;
+    } else if (typeof pathSrc === 'string') {
+      path = pathSrc;
+    }
+
+    if (path == null || path == '') {
+      continue;
+    }
+
+    if (fullPath === '') {
+      fullPath = path;
+    } else if (fullPath.endsWith('/') && path.startsWith('/')) {
+      fullPath += path.replace(/^\//, '');
+    } else if (fullPath.endsWith('/') || path.startsWith('/')) {
+      fullPath += path;
+    } else {
+      fullPath += `/${path}`;
+    }
+  }
+
+  return fullPath;
+}
+

package/lib/utils/makeAppendProblemDetails.ts

@@ -0,0 +1,57 @@
+import type {ProblemDetailsParam, ProblemDetails} from '../types.js';
+
+export type AppendProblemDetails = (args: {
+  status: number;
+  title?: string,
+  detail?: string,
+  param?: ProblemDetailsParam;
+}) => void;
+
+export type ProblemDetailsParamsRefs = {
+  title?: string;
+  detail?: string;
+  httpStatus?: number;
+  problemDetails?: ProblemDetails;
+};
+
+export function makeAppendProblemDetails(
+  refs: ProblemDetailsParamsRefs
+): AppendProblemDetails {
+  function appendProblemDetails({
+    title,
+    detail,
+    status,
+    param,
+  }: {
+    status: number;
+    title?: string,
+    detail?: string,
+    param?: ProblemDetailsParam;
+  }) {
+    if (refs.httpStatus == null) {
+      refs.httpStatus = status;
+    } else if (
+      refs.httpStatus !== status &&
+      refs.httpStatus < 400
+    ) {
+      refs.httpStatus = status
+    }
+
+    if (!refs.problemDetails) {
+      refs.problemDetails = {
+        title: title ??= "Bad request",
+        detail: detail ??= "Invalid parameters",
+      };
+    }
+    
+    if (param) {
+      if (!Array.isArray(refs.problemDetails.errors)) {
+        refs.problemDetails.errors = [param];
+      } else {
+        refs.problemDetails.errors.push(param);
+      }
+    }
+  }
+
+  return appendProblemDetails;
+}

package/lib/utils/makeURLPattern.ts

@@ -0,0 +1,18 @@
+import url from 'node:url';
+
+
+type URLPatternConstructor = new (input: string, baseURL: string) => URLPattern;
+
+/**
+ * Work-around for how URLPatterns are currently supported across runtimes.
+ * This requires node v23 and above to run.
+ */
+export function makeURLPattern(pattern: string, baseURL: string): URLPattern {
+  if (typeof URLPattern === 'undefined') {
+    const URLPattern = (url as unknown as { URLPattern: URLPatternConstructor }).URLPattern;
+
+    return new URLPattern(pattern, baseURL);
+  }
+
+  return new URLPattern(pattern, baseURL);
+}

package/lib/utils/normalizeURL.ts

@@ -0,0 +1,15 @@
+
+
+/**
+ * Maps the URL of the request to the root IRI.
+ */
+export function normalizeURL(rootIRI: string, urlStr: string): string {
+    const sourceURL = new URL(urlStr);
+    const targetURL = new URL(rootIRI);
+    
+    targetURL.pathname = sourceURL.pathname;
+    targetURL.search = sourceURL.search;
+    targetURL.hash = sourceURL.hash;
+
+    return targetURL.toString();
+}

package/lib/utils/parseSearchParams.ts

@@ -0,0 +1,36 @@
+import type {ActionSpec, ContextState} from "../actions/spec.js";
+import type { EmptyObject, JSONObject, JSONValue } from "../jsonld.js";
+
+export function parseSearchParams<
+  ActionState extends ContextState = EmptyObject,
+>(
+  spec: ActionSpec<ActionState>,
+  searchParams: URLSearchParams,
+): JSONObject {
+  const body: Record<string, JSONValue> = {};
+
+  for (const [key, specItem] of Object.entries(spec)) {
+    const value = searchParams.get(key);
+
+    if (
+      specItem.dataType === "number" &&
+      Array.isArray(value) &&
+      value !== null
+    ) {
+      body[key] = value.map(Number);
+    } else if (
+      specItem.dataType === "number" &&
+      value !== null &&
+      isNaN(Number(value))
+    ) {
+      // keeping the number value as a string allows error handling to work with it
+      body[key] = value;
+    } else if (specItem.dataType === "number" && value !== null) {
+      body[key] = Number(value);
+    } else if (value !== null) {
+      body[key] = value;
+    }
+  }
+
+  return body;
+}