@occultist/occultist 0.0.1

package/lib/actions/actions.ts

@@ -0,0 +1,795 @@
+import {CacheInstanceArgs} from '../cache/types.js';
+import type {JSONLDContext, JSONObject, TypeDef} from "../jsonld.js";
+import type {Registry} from '../registry.js';
+import type {Scope} from "../scopes.js";
+import {getActionContext} from "../utils/getActionContext.js";
+import {getPropertyValueSpecifications} from "../utils/getPropertyValueSpecifications.js";
+import {isPopulatedObject} from '../utils/isPopulatedObject.js';
+import {joinPaths} from "../utils/joinPaths.js";
+import {AfterDefinition, BeforeDefinition, type ActionMeta} from "./meta.js";
+import type {ActionSpec, ContextState} from "./spec.js";
+import type {HandlerArgs, HandleRequestArgs, HandlerFn, HandlerMeta, HandlerObj, HandlerValue, HintArgs, ImplementedAction} from './types.js';
+import {ResponseTypes} from './writer.js';
+
+
+export type DefineArgs<
+  Term extends string = string,
+  Spec extends ActionSpec = ActionSpec,
+> = {
+  typeDef?: TypeDef<Term>
+  spec?: Spec;
+};
+
+
+function isHandlerObj<
+  State extends ContextState = ContextState,
+  Spec extends ActionSpec = ActionSpec
+>(handler: unknown): handler is HandlerObj<State, Spec> {
+  return isPopulatedObject(handler);
+}
+
+/**
+ * A handler definition which can be pulled from a registry, scope or action
+ * after an action is defined.
+ */
+export class HandlerDefinition<
+  State extends ContextState = ContextState,
+  Spec extends ActionSpec = ActionSpec,
+> {
+  name: string;
+  contentType: string;
+  handler: HandlerFn | HandlerValue;
+  meta: HandlerMeta;
+  action: ImplementedAction<State, Spec>;
+  cache: ReadonlyArray<CacheInstanceArgs>;
+  
+  constructor(
+    name: string,
+    contentType: string,
+    handler: HandlerFn | HandlerValue,
+    meta: HandlerMeta,
+    action: ImplementedAction<State, Spec>,
+    actionMeta: ActionMeta,
+  ) {
+    this.name = name;
+    this.contentType = contentType;
+    this.handler = handler;
+    this.action = action;
+    this.meta = Object.freeze({ ...meta ?? {} });
+    
+    const cache: CacheInstanceArgs[] = [];
+
+    for (let i = 0; i < actionMeta.cache.length; i++) {
+      cache.push(Object.freeze({ ...actionMeta.cache[i] }));
+    }
+
+    this.cache = Object.freeze(cache);
+
+    Object.freeze(this);
+  }
+
+  get [Symbol.toStringTag]() {
+    return `name=${this.name} contentType=${this.contentType}`;
+  }
+}
+
+export interface Handleable<
+  State extends ContextState = ContextState,
+  Spec extends ActionSpec = ActionSpec,
+> {
+  
+  /**
+   * Defines the final handler for this content type.
+   *
+   * An action can have multiple handlers defined
+   * each for a different set of content types.
+   */
+  handle(
+    contentType: string | string[],
+    handler: HandlerValue | HandlerFn<State, Spec>,
+  ): FinalizedAction<State, Spec>;
+
+  handle(
+    args: HandlerObj<State, Spec>,
+  ): FinalizedAction<State, Spec>;
+}
+
+export class FinalizedAction<
+  State extends ContextState = ContextState,
+  Spec extends ActionSpec = ActionSpec,
+> implements
+  Handleable<State, Spec>,
+  ImplementedAction<State, Spec>
+{
+  #spec: Spec;
+  #meta: ActionMeta<State, Spec>;
+  #typeDef?: TypeDef;
+  #handlers: Map<string, HandlerDefinition<State, Spec>>;
+
+  constructor(
+    typeDef: TypeDef | undefined,
+    spec: Spec,
+    meta: ActionMeta<State, Spec>,
+    handlerArgs: HandlerObj<State, Spec>,
+  ) {
+    this.#typeDef = typeDef;
+    this.#spec = spec ?? {} as Spec;
+    this.#meta = meta;
+
+    this.#meta.action = this as unknown as ImplementedAction<State, Spec>;
+
+    const handlers: Map<string, HandlerDefinition<State, Spec>> = new Map();
+
+    if (typeof handlerArgs.contentType === 'string') {
+      handlers.set(handlerArgs.contentType, new HandlerDefinition(
+        this.name,
+        handlerArgs.contentType,
+        handlerArgs.handler,
+        handlerArgs.meta,
+        this as unknown as ImplementedAction<State, Spec>,
+        this.#meta,
+      ));
+    } else if (isPopulatedObject(handlerArgs)) {
+      for (let i = 0; i < handlerArgs.contentType.length; i++) {
+        handlers.set(handlerArgs.contentType[i], new HandlerDefinition(
+          this.name,
+          handlerArgs.contentType[i],
+          handlerArgs.handler,
+          handlerArgs.meta,
+          this as unknown as ImplementedAction<State, Spec>,
+          this.#meta,
+        ));
+      }
+    }
+
+    this.#handlers = handlers;
+  }
+
+  static fromHandlers<
+    State extends ContextState = ContextState,
+    Spec extends ActionSpec = ActionSpec,
+  >(
+    typeDef: TypeDef | undefined,
+    spec: Spec,
+    meta: ActionMeta<State, Spec>,
+    contextType: string | string[],
+    handler: HandlerValue | HandlerFn<State, Spec>,
+  ): FinalizedAction<State, Spec>;
+
+  static fromHandlers<
+    State extends ContextState = ContextState,
+    Spec extends ActionSpec = ActionSpec,
+  >(
+    typeDef: TypeDef | undefined,
+    spec: Spec,
+    meta: ActionMeta<State, Spec>,
+    handlerArgs: HandlerObj<State, Spec>,
+  ): FinalizedAction<State, Spec>;
+
+  static fromHandlers<
+    State extends ContextState = ContextState,
+    Spec extends ActionSpec = ActionSpec,
+  >(
+    typeDef: TypeDef | undefined,
+    spec: Spec,
+    meta: ActionMeta<State, Spec>,
+    arg3: string | string[] | HandlerObj<State, Spec>,
+    arg4?: HandlerValue | HandlerFn<State, Spec>,
+  ): FinalizedAction<State, Spec> {
+    if (Array.isArray(arg3) || typeof arg3 === 'string') {
+      return new FinalizedAction<State, Spec>(typeDef, spec, meta, {
+        contentType: arg3,
+        handler: arg4,
+      });
+    }
+
+    return new FinalizedAction(typeDef, spec, meta, arg3);
+  }
+
+  static async toJSONLD(
+    action: ImplementedAction,
+    scope: Scope,
+  ): Promise<JSONObject | null> {
+    if (scope == null || action.typeDef == null) {
+      return null;
+    }
+
+    const apiSpec = await getPropertyValueSpecifications(action.spec);
+
+    return {
+      '@context': action.context,
+      '@id': joinPaths(action.registry.rootIRI, scope.path, action.name),
+      '@type': action.term,
+      target: {
+        '@type': 'https://schema.org/EntryPoint',
+        httpMethod: action.method,
+        urlTemplate: action.template,
+        contentType: 'application/ld+json',
+      },
+      ...apiSpec,
+    };
+  }
+
+  get public(): boolean {
+    return this.#meta.public;
+  }
+
+  get method(): string {
+    return this.#meta.method;
+  }
+  
+  get term(): string | undefined {
+    return this.#typeDef?.term;
+  }
+
+  get type(): string | undefined {
+    return this.#typeDef?.type;
+  }
+
+  get typeDef(): TypeDef | undefined {
+    return this.#typeDef;
+  }
+
+  get name(): string {
+    return this.#meta.name;
+  }
+
+  get template(): string {
+    return this.#meta.uriTemplate;
+  }
+
+  get pattern(): URLPattern {
+    return this.#meta.path.pattern;
+  }
+
+  get spec(): Spec {
+    return this.#spec;
+  }
+
+  get scope(): Scope | undefined {
+    return this.#meta.scope
+  }
+
+  get registry(): Registry {
+    return this.#meta.registry;
+  }
+  
+  get handlers(): HandlerDefinition<State, Spec>[] {
+    return Array.from(this.#handlers.values());
+  }
+
+  get contentTypes(): string[] {
+    return Array.from(this.#handlers.keys());
+  }
+
+  get context(): JSONObject {
+    return getActionContext({
+      spec: this.#spec,
+      //vocab: this.#vocab,
+      //aliases: this.#aliases,
+    });
+  }
+ 
+  url(): string {
+    return joinPaths(this.#meta.registry.rootIRI, this.#meta.path.normalized);
+  }
+
+  jsonld(): Promise<JSONObject | null> {
+    const scope = this.#meta.scope;
+
+    return FinalizedAction.toJSONLD(
+      this as unknown as ImplementedAction,
+      scope
+    );
+  }
+
+  jsonldPartial(): { '@type': string, '@id': string } | null {
+    const scope = this.#meta.scope;
+    const typeDef = this.#typeDef;
+
+    if (scope == null || typeDef == null) {
+      return null;
+    }
+    
+    return {
+      '@type': typeDef.type,
+      '@id': joinPaths(scope.url(), this.#meta.name),
+    };
+  }
+
+  handle(
+    contentType: string | string[],
+    handler: HandlerFn<State, Spec> | HandlerValue,
+  ): FinalizedAction<State, Spec>;
+
+  handle(
+    args: HandlerObj<State, Spec>,
+  ): FinalizedAction<State, Spec>;
+  
+  handle(
+    arg1: string | string[] | HandlerObj<State, Spec>,
+    arg2?: HandlerFn<State, Spec>,
+  ): FinalizedAction<State, Spec> {
+    let contentType: string | string[];
+    let handler: HandlerFn<State, Spec> | HandlerValue;
+    let meta: HandlerMeta;
+
+    if (isHandlerObj(arg1)) {
+      contentType = arg1.contentType;
+      handler = arg1.handler;
+      meta = Object.assign(Object.create(null), arg1.meta);
+
+      if (arg1.meta != null) {
+        for (const sym of Object.getOwnPropertySymbols(arg1.meta)) {
+          meta[sym] = arg1.meta[sym];
+        }
+      }
+    } else {
+      contentType = arg1;
+      handler = arg2;
+      meta = Object.create(null);
+    }
+
+    if (!Array.isArray(contentType)) {
+      this.#handlers.set(contentType, new HandlerDefinition(
+        this.#meta.name,
+        contentType,
+        handler,
+        meta,
+        this as unknown as ImplementedAction<State, Spec>,
+        this.#meta,
+      ));
+    } else {
+      for (let i = 0; i < contentType.length; i++) {
+        this.#handlers.set(contentType[i], new HandlerDefinition(
+          this.#meta.name,
+          contentType[i],
+          handler,
+          meta,
+          this as unknown as ImplementedAction<State, Spec>,
+          this.#meta,
+        ));
+      }
+    }
+
+    return this;
+  }
+
+  async handleRequest(args: HandleRequestArgs): Promise<ResponseTypes> {
+    const handler = this.#handlers.get(args.contentType as string);
+
+    return this.#meta.handleRequest({
+      ...args,
+      spec: this.#spec,
+      handler,
+    });
+  }
+}
+
+export interface Applicable<ActionType> {
+  use(): ActionType;
+}
+
+export class DefinedAction<
+  State extends ContextState = ContextState,
+  Term extends string = string,
+  Spec extends ActionSpec = ActionSpec,
+> implements
+  Applicable<DefinedAction<State, Term, Spec>>,
+  Handleable<State, Spec>,
+  ImplementedAction<State, Spec>
+{
+  #spec: Spec;
+  #meta: ActionMeta<State, Spec>;
+  #typeDef?: TypeDef;
+
+  constructor(
+    typeDef: TypeDef | undefined,
+    spec: Spec,
+    meta: ActionMeta<State, Spec>,
+  ) {
+    this.#spec = spec ?? {} as Spec;
+    this.#meta = meta;
+    this.#typeDef = typeDef;
+
+    this.#meta.action = this as unknown as ImplementedAction<State, Spec>;
+  }
+
+  get public(): boolean {
+    return this.#meta.public;
+  }
+
+  get method(): string {
+    return this.#meta.method;
+  }
+  
+  get term(): string | undefined {
+    return this.#typeDef?.term;
+  }
+
+  get type(): string | undefined {
+    return this.#typeDef?.type;
+  }
+
+  get typeDef(): TypeDef | undefined {
+    return this.#typeDef;
+  }
+
+  get name(): string {
+    return this.#meta.name;
+  }
+
+  get template(): string {
+    return this.#meta.uriTemplate;
+  }
+
+  get pattern(): URLPattern {
+    return this.#meta.path.pattern;
+  }
+
+  get path(): string {
+    return this.#meta.path.normalized;
+  }
+
+  get spec(): Spec {
+    return this.#spec;
+  }
+
+  get scope(): Scope | undefined {
+    return this.#meta.scope;
+  }
+
+  get registry(): Registry {
+    return this.#meta.registry;
+  }
+
+  get handlers(): HandlerDefinition<State, Spec>[] {
+    return [];
+  }
+
+  get contentTypes(): string[] {
+    return [];
+  }
+ 
+  url(): string {
+    return '';
+  }
+
+  get context(): JSONLDContext {
+    return getActionContext({
+      spec: this.#spec,
+      // vocab: this.#vocab,
+      // aliases: this.#aliases,
+    });
+  }
+
+  jsonld(): Promise<JSONObject | null> {
+    const scope = this.#meta.scope;
+
+    return FinalizedAction.toJSONLD(
+      this as unknown as ImplementedAction,
+      scope
+    );
+  }
+
+  jsonldPartial(): { '@type': string, '@id': string } | null {
+    const scope = this.#meta.scope;
+    const typeDef = this.#typeDef;
+
+    if (scope == null || typeDef == null) {
+      return null;
+    }
+    
+    return {
+      '@type': typeDef.type,
+      '@id': joinPaths(scope.url(), this.#meta.name),
+    };
+  }
+
+  /**
+   * Defines a cache handling rule for this action.
+   *
+   * Defining caching rules after the `action.define()` method is safer
+   * if validating and transforming the action payload might cause
+   * auth sensitive checks to be run which might reject the request.
+   */
+  cache(args: CacheInstanceArgs): DefinedAction<State, string, Spec> {
+    if (this.#meta.cache.length !== 0 &&
+        this.#meta.cacheOccurance === BeforeDefinition) {
+      throw new Error(
+        'Action cache may be defined either before or after ' +
+        'the definition method is called, but not both.');
+    } else if (this.#meta.cacheOccurance === BeforeDefinition) {
+      this.#meta.cacheOccurance = AfterDefinition;
+    }
+
+    this.#meta.cache.push(args);
+
+    return this;
+  }
+  
+  meta(): DefinedAction<State, string, Spec> {
+    return this;
+  }
+
+  use(): DefinedAction<State, string, Spec> {
+    return this;
+  }
+  
+  handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State, Spec>): FinalizedAction<State, Spec>;
+  handle(args: HandlerObj<State, Spec>): FinalizedAction<State, Spec>;
+  handle(arg1: unknown, arg2?: unknown): FinalizedAction<State, Spec> {
+    return FinalizedAction.fromHandlers(
+      this.#typeDef,
+      this.#spec,
+      this.#meta,
+      arg1 as string | string[],
+      arg2 as HandlerFn<State, Spec>,
+    );
+  }
+
+  async handleRequest(args: HandleRequestArgs): Promise<ResponseTypes> {
+    return this.#meta.handleRequest({
+      ...args,
+      spec: this.#spec,
+    });
+  }
+
+}
+
+export class Action<
+  State extends ContextState = ContextState,
+> implements
+  Applicable<Action>,
+  Handleable<State>,
+  ImplementedAction<State>
+{
+  #spec: ActionSpec = {};
+  #meta: ActionMeta<State>;
+
+  constructor(
+    meta: ActionMeta<State>,
+  ) {
+    this.#meta = meta;
+    this.#meta.action = this as ImplementedAction<State, {}>;
+  }
+
+  get public(): boolean {
+    return this.#meta.public;
+  }
+
+  get method(): string {
+    return this.#meta.method;
+  }
+  
+  get term(): string | undefined {
+    return undefined;
+  }
+
+  get type(): string | undefined {
+    return undefined;
+  }
+
+  get typeDef(): TypeDef | undefined {
+    return undefined;
+  }
+
+  get name(): string {
+    return this.#meta.name;
+  }
+
+  get template(): string {
+    return this.#meta.uriTemplate;
+  }
+
+  get pattern(): URLPattern {
+    return this.#meta.path.pattern;
+  }
+
+
+  get path(): string {
+    return this.#meta.path.normalized;
+  }
+
+  get spec(): ActionSpec {
+    return this.#spec;
+  }
+
+  get scope(): Scope | undefined {
+    return this.#meta.scope;
+  }
+
+  get registry(): Registry {
+    return this.#meta.registry;
+  }
+  
+  get handlers(): HandlerDefinition[] {
+    return [];
+  }
+
+  get contentTypes(): string[] {
+    return [];
+  }
+
+  get context(): JSONObject {
+    return getActionContext({
+      spec: this.#spec,
+      //vocab: this.#vocab,
+      //aliases: this.#aliases,
+    });
+  }
+
+  url(): string {
+    return '';
+  }
+
+  jsonld(): Promise<null> {
+    return Promise.resolve(null);
+  }
+
+  jsonldPartial(): { '@type': string, '@id': string } | null {
+    return null;
+  }
+
+  use(): Action<State> {
+    return this;
+  }
+
+  define<
+    Term extends string = string,
+    Spec extends ActionSpec = ActionSpec,
+  >(args: DefineArgs<Term, Spec>): DefinedAction<State, Term, Spec> {
+    return new DefinedAction<State, Term, Spec>(
+      args.typeDef,
+      args.spec ?? {} as Spec,
+      this.#meta as unknown as ActionMeta<State, Spec>,
+    );
+  }
+  
+  handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State>): FinalizedAction<State>;
+  handle(args: HandlerObj<State>): FinalizedAction<State>;
+  handle(arg1: unknown, arg2?: unknown): FinalizedAction<State> {
+    return FinalizedAction.fromHandlers(
+      null,
+      this.#spec,
+      this.#meta,
+      arg1 as string | string[],
+      arg2 as HandlerFn<State>,
+    );
+  }
+
+  async handleRequest(args: HandleRequestArgs): Promise<ResponseTypes> {
+    return this.#meta.handleRequest({
+      ...args,
+      spec: this.#spec,
+    });
+  }
+
+}
+
+export class PreAction<
+  State extends ContextState = ContextState,
+> implements
+  Applicable<Action>,
+  Handleable<State>
+{
+  #meta: ActionMeta<State>;
+
+  constructor(
+    meta: ActionMeta<State>,
+  ) {
+    this.#meta = meta;
+  }
+
+  use() {
+    return new Action(
+      this.#meta,
+    );
+  }
+
+  define<
+    Term extends string = string,
+    Spec extends ActionSpec = ActionSpec,
+  >(args: DefineArgs<Term, Spec>): DefinedAction<State, Term, Spec> {
+    return new DefinedAction<State, Term, Spec>(
+      args.typeDef,
+      args.spec,
+      this.#meta as unknown as ActionMeta<State, Spec>,
+    );
+  }
+  
+  handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State>): FinalizedAction<State>;
+  handle(args: HandlerObj<State>): FinalizedAction<State>;
+  handle(arg1: unknown, arg2?: unknown): FinalizedAction<State> {
+    return FinalizedAction.fromHandlers(
+      null,
+      {},
+      this.#meta,
+      arg1 as string | string[],
+      arg2 as HandlerFn<State>,
+    );
+  }
+}
+
+export class Endpoint<
+  State extends ContextState = ContextState,
+> implements
+  Applicable<Action>,
+  Handleable<State>
+{
+  #meta: ActionMeta<State>;
+
+  constructor(
+    meta: ActionMeta<State>,
+  ) {
+    this.#meta = meta;
+  }
+  
+  hint(hints: HintArgs): Endpoint<State> {
+    this.#meta.hints.push(hints);
+
+    return this;
+  }
+
+  compress(): Endpoint<State> {
+    return this;
+  }
+  
+  cache(args: CacheInstanceArgs) {
+    this.#meta.cache.push(args);
+
+    return this;
+  }
+
+  etag() {
+    return this;
+  }
+
+  use(): Action<State> {
+    return new Action<State>(this.#meta);
+  }
+
+  define<
+    Term extends string = string,
+    Spec extends ActionSpec = ActionSpec,
+  >(args: DefineArgs<Term, Spec>): DefinedAction<State, Term, Spec> {
+    return new DefinedAction<State, Term, Spec>(
+      args.typeDef,
+      args.spec,
+      this.#meta as ActionMeta<State, Spec>,
+    );
+  }
+
+  handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State>): FinalizedAction<State>;
+  handle(args: HandlerObj<State>): FinalizedAction<State>;
+  handle(arg1: unknown, arg2?: unknown): FinalizedAction<State> {
+    return FinalizedAction.fromHandlers(
+      undefined,
+      {},
+      this.#meta,
+      arg1 as string | string[],
+      arg2 as HandlerFn<State>,
+    );
+  }
+}
+
+export class ActionAuth<
+  State extends ContextState = ContextState,
+> {
+  #meta: ActionMeta<State>;
+
+  constructor(meta: ActionMeta<State>) {
+    this.#meta = meta;
+  }
+
+  public(): Endpoint<State> {
+    this.#meta.public = true;
+    
+    return new Endpoint(this.#meta);
+  }
+
+  private(): Endpoint<State> {
+    return new Endpoint(this.#meta);
+  }
+}
+