@occultist/occultist 0.0.4 → 0.0.6

package/lib/actions/actions.ts

@@ -1,15 +1,15 @@
-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';
+import type {CacheInstanceArgs} from '../cache/types.ts';
+import type {JSONLDContext, JSONObject, TypeDef} from "../jsonld.ts";
+import type {Registry} from '../registry.ts';
+import type {Scope} from "../scopes.ts";
+import {getActionContext} from "../utils/getActionContext.ts";
+import {getPropertyValueSpecifications} from "../utils/getPropertyValueSpecifications.ts";
+import {isPopulatedObject} from '../utils/isPopulatedObject.ts';
+import {joinPaths} from "../utils/joinPaths.ts";
+import {AfterDefinition, BeforeDefinition, type ActionMeta} from "./meta.ts";
+import type {ActionSpec, ContextState} from "./spec.ts";
+import type {AuthMiddleware, AuthState, HandleRequestArgs, HandlerFn, HandlerMeta, HandlerObj, HandlerValue, HintArgs, ImplementedAction} from './types.ts';
+import {type ResponseTypes} from './writer.ts';
 
 
 export type DefineArgs<
@@ -23,8 +23,9 @@ export type DefineArgs<
 
 function isHandlerObj<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec
->(handler: unknown): handler is HandlerObj<State, Spec> {
+>(handler: unknown): handler is HandlerObj<State, Auth, Spec> {
   return isPopulatedObject(handler);
 }
 
@@ -34,13 +35,14 @@ function isHandlerObj<
  */
 export class HandlerDefinition<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec,
 > {
   name: string;
   contentType: string;
   handler: HandlerFn | HandlerValue;
   meta: HandlerMeta;
-  action: ImplementedAction<State, Spec>;
+  action: ImplementedAction<State, Auth, Spec>;
   cache: ReadonlyArray<CacheInstanceArgs>;
   
   constructor(
@@ -48,7 +50,7 @@ export class HandlerDefinition<
     contentType: string,
     handler: HandlerFn | HandlerValue,
     meta: HandlerMeta,
-    action: ImplementedAction<State, Spec>,
+    action: ImplementedAction<State, Auth, Spec>,
     actionMeta: ActionMeta,
   ) {
     this.name = name;
@@ -75,6 +77,7 @@ export class HandlerDefinition<
 
 export interface Handleable<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec,
 > {
   
@@ -86,39 +89,40 @@ export interface Handleable<
    */
   handle(
     contentType: string | string[],
-    handler: HandlerValue | HandlerFn<State, Spec>,
-  ): FinalizedAction<State, Spec>;
+    handler: HandlerValue | HandlerFn<State, Auth, Spec>,
+  ): FinalizedAction<State, Auth, Spec>;
 
   handle(
-    args: HandlerObj<State, Spec>,
-  ): FinalizedAction<State, Spec>;
+    args: HandlerObj<State, Auth, Spec>,
+  ): FinalizedAction<State, Auth, Spec>;
 }
 
 export class FinalizedAction<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Spec extends ActionSpec = ActionSpec,
 > implements
-  Handleable<State, Spec>,
-  ImplementedAction<State, Spec>
+  Handleable<State, Auth, Spec>,
+  ImplementedAction<State, Auth, Spec>
 {
   #spec: Spec;
-  #meta: ActionMeta<State, Spec>;
+  #meta: ActionMeta<State, Auth, Spec>;
   #typeDef?: TypeDef;
-  #handlers: Map<string, HandlerDefinition<State, Spec>>;
+  #handlers: Map<string, HandlerDefinition<State, Auth, Spec>>;
 
   constructor(
     typeDef: TypeDef | undefined,
     spec: Spec,
-    meta: ActionMeta<State, Spec>,
-    handlerArgs: HandlerObj<State, Spec>,
+    meta: ActionMeta<State, Auth, Spec>,
+    handlerArgs: HandlerObj<State, Auth, Spec>,
   ) {
     this.#typeDef = typeDef;
     this.#spec = spec ?? {} as Spec;
     this.#meta = meta;
 
-    this.#meta.action = this as unknown as ImplementedAction<State, Spec>;
+    this.#meta.action = this as unknown as ImplementedAction<State, Auth, Spec>;
 
-    const handlers: Map<string, HandlerDefinition<State, Spec>> = new Map();
+    const handlers: Map<string, HandlerDefinition<State, Auth, Spec>> = new Map();
 
     if (typeof handlerArgs.contentType === 'string') {
       handlers.set(handlerArgs.contentType, new HandlerDefinition(
@@ -126,7 +130,7 @@ export class FinalizedAction<
         handlerArgs.contentType,
         handlerArgs.handler,
         handlerArgs.meta,
-        this as unknown as ImplementedAction<State, Spec>,
+        this as unknown as ImplementedAction<State, Auth, Spec>,
         this.#meta,
       ));
     } else if (isPopulatedObject(handlerArgs)) {
@@ -136,7 +140,7 @@ export class FinalizedAction<
           handlerArgs.contentType[i],
           handlerArgs.handler,
           handlerArgs.meta,
-          this as unknown as ImplementedAction<State, Spec>,
+          this as unknown as ImplementedAction<State, Auth, Spec>,
           this.#meta,
         ));
       }
@@ -147,37 +151,40 @@ export class FinalizedAction<
 
   static fromHandlers<
     State extends ContextState = ContextState,
+    Auth extends AuthState = AuthState,
     Spec extends ActionSpec = ActionSpec,
   >(
     typeDef: TypeDef | undefined,
     spec: Spec,
-    meta: ActionMeta<State, Spec>,
+    meta: ActionMeta<State, Auth, Spec>,
     contextType: string | string[],
-    handler: HandlerValue | HandlerFn<State, Spec>,
-  ): FinalizedAction<State, Spec>;
+    handler: HandlerValue | HandlerFn<State, Auth, Spec>,
+  ): FinalizedAction<State, Auth, Spec>;
 
   static fromHandlers<
     State extends ContextState = ContextState,
+    Auth extends AuthState = AuthState,
     Spec extends ActionSpec = ActionSpec,
   >(
     typeDef: TypeDef | undefined,
     spec: Spec,
-    meta: ActionMeta<State, Spec>,
-    handlerArgs: HandlerObj<State, Spec>,
-  ): FinalizedAction<State, Spec>;
+    meta: ActionMeta<State, Auth, Spec>,
+    handlerArgs: HandlerObj<State, Auth, Spec>,
+  ): FinalizedAction<State, Auth, Spec>;
 
   static fromHandlers<
     State extends ContextState = ContextState,
+    Auth extends AuthState = AuthState,
     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> {
+    meta: ActionMeta<State, Auth, Spec>,
+    arg3: string | string[] | HandlerObj<State, Auth, Spec>,
+    arg4?: HandlerValue | HandlerFn<State, Auth, Spec>,
+  ): FinalizedAction<State, Auth, Spec> {
     if (Array.isArray(arg3) || typeof arg3 === 'string') {
-      return new FinalizedAction<State, Spec>(typeDef, spec, meta, {
+      return new FinalizedAction<State, Auth, Spec>(typeDef, spec, meta, {
         contentType: arg3,
         handler: arg4,
       });
@@ -254,7 +261,7 @@ export class FinalizedAction<
     return this.#meta.registry;
   }
   
-  get handlers(): HandlerDefinition<State, Spec>[] {
+  get handlers(): HandlerDefinition<State, Auth, Spec>[] {
     return Array.from(this.#handlers.values());
   }
 
@@ -274,6 +281,15 @@ export class FinalizedAction<
     return joinPaths(this.#meta.registry.rootIRI, this.#meta.path.normalized);
   }
 
+  /**
+   * Retrives the handler configured for the given content type.
+   *
+   * @param contentType   The content type.
+   */
+  handlerFor(contentType: string): HandlerDefinition<State, Auth, Spec> | undefined {
+    return this.#handlers.get(contentType);
+  }
+
   jsonld(): Promise<JSONObject | null> {
     const scope = this.#meta.scope;
 
@@ -299,19 +315,19 @@ export class FinalizedAction<
 
   handle(
     contentType: string | string[],
-    handler: HandlerFn<State, Spec> | HandlerValue,
-  ): FinalizedAction<State, Spec>;
+    handler: HandlerFn<State, Auth, Spec> | HandlerValue,
+  ): FinalizedAction<State, Auth, Spec>;
 
   handle(
-    args: HandlerObj<State, Spec>,
-  ): FinalizedAction<State, Spec>;
+    args: HandlerObj<State, Auth, Spec>,
+  ): FinalizedAction<State, Auth, Spec>;
   
   handle(
-    arg1: string | string[] | HandlerObj<State, Spec>,
-    arg2?: HandlerFn<State, Spec>,
-  ): FinalizedAction<State, Spec> {
+    arg1: string | string[] | HandlerObj<State, Auth, Spec>,
+    arg2?: HandlerFn<State, Auth, Spec>,
+  ): FinalizedAction<State, Auth, Spec> {
     let contentType: string | string[];
-    let handler: HandlerFn<State, Spec> | HandlerValue;
+    let handler: HandlerFn<State, Auth, Spec> | HandlerValue;
     let meta: HandlerMeta;
 
     if (isHandlerObj(arg1)) {
@@ -336,7 +352,7 @@ export class FinalizedAction<
         contentType,
         handler,
         meta,
-        this as unknown as ImplementedAction<State, Spec>,
+        this as unknown as ImplementedAction<State, Auth, Spec>,
         this.#meta,
       ));
     } else {
@@ -346,7 +362,7 @@ export class FinalizedAction<
           contentType[i],
           handler,
           meta,
-          this as unknown as ImplementedAction<State, Spec>,
+          this as unknown as ImplementedAction<State, Auth, Spec>,
           this.#meta,
         ));
       }
@@ -355,7 +371,7 @@ export class FinalizedAction<
     return this;
   }
 
-  async handleRequest(args: HandleRequestArgs): Promise<ResponseTypes> {
+  handleRequest(args: HandleRequestArgs): Promise<ResponseTypes> {
     const handler = this.#handlers.get(args.contentType as string);
 
     return this.#meta.handleRequest({
@@ -364,6 +380,10 @@ export class FinalizedAction<
       handler,
     });
   }
+
+  perform(req: Request): Promise<Response> {
+    return this.#meta.perform(req);
+  }
 }
 
 export interface Applicable<ActionType> {
@@ -372,27 +392,28 @@ export interface Applicable<ActionType> {
 
 export class DefinedAction<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
   Term extends string = string,
   Spec extends ActionSpec = ActionSpec,
 > implements
-  Applicable<DefinedAction<State, Term, Spec>>,
-  Handleable<State, Spec>,
-  ImplementedAction<State, Spec>
+  Applicable<DefinedAction<State, Auth, Term, Spec>>,
+  Handleable<State, Auth, Spec>,
+  ImplementedAction<State, Auth, Spec>
 {
   #spec: Spec;
-  #meta: ActionMeta<State, Spec>;
+  #meta: ActionMeta<State, Auth, Spec>;
   #typeDef?: TypeDef;
 
   constructor(
     typeDef: TypeDef | undefined,
     spec: Spec,
-    meta: ActionMeta<State, Spec>,
+    meta: ActionMeta<State, Auth, Spec>,
   ) {
     this.#spec = spec ?? {} as Spec;
     this.#meta = meta;
     this.#typeDef = typeDef;
 
-    this.#meta.action = this as unknown as ImplementedAction<State, Spec>;
+    this.#meta.action = this as unknown as ImplementedAction<State, Auth, Spec>;
   }
 
   get public(): boolean {
@@ -443,7 +464,7 @@ export class DefinedAction<
     return this.#meta.registry;
   }
 
-  get handlers(): HandlerDefinition<State, Spec>[] {
+  get handlers(): HandlerDefinition<State, Auth, Spec>[] {
     return [];
   }
 
@@ -455,6 +476,13 @@ export class DefinedAction<
     return '';
   }
 
+  /**
+   * Retrives the handler configured for the given content type.
+   *
+   * @param contentType   The content type.
+   */
+  handlerFor(_contentType: string): undefined {}
+
   get context(): JSONLDContext {
     return getActionContext({
       spec: this.#spec,
@@ -493,7 +521,7 @@ export class DefinedAction<
    * 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> {
+  cache(args: CacheInstanceArgs): DefinedAction<State, Auth, Term, Spec> {
     if (this.#meta.cache.length !== 0 &&
         this.#meta.cacheOccurance === BeforeDefinition) {
       throw new Error(
@@ -508,23 +536,23 @@ export class DefinedAction<
     return this;
   }
   
-  meta(): DefinedAction<State, string, Spec> {
+  meta(): DefinedAction<State, Auth, Term, Spec> {
     return this;
   }
 
-  use(): DefinedAction<State, string, Spec> {
+  use(): DefinedAction<State, Auth, Term, 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> {
+  handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State, Auth, Spec>): FinalizedAction<State, Auth, Spec>;
+  handle(args: HandlerObj<State, Auth, Spec>): FinalizedAction<State, Auth, Spec>;
+  handle(arg1: unknown, arg2?: unknown): FinalizedAction<State, Auth, Spec> {
     return FinalizedAction.fromHandlers(
       this.#typeDef,
       this.#spec,
       this.#meta,
       arg1 as string | string[],
-      arg2 as HandlerFn<State, Spec>,
+      arg2 as HandlerFn<State, Auth, Spec>,
     );
   }
 
@@ -535,10 +563,15 @@ export class DefinedAction<
     });
   }
 
+  perform(req: Request): Promise<Response> {
+    return this.#meta.perform(req);
+  }
+
 }
 
 export class Action<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
 > implements
   Applicable<Action>,
   Handleable<State>,
@@ -623,6 +656,13 @@ export class Action<
     return '';
   }
 
+  /**
+   * Retrives the handler configured for the given content type.
+   *
+   * @param contentType   The content type.
+   */
+  handlerFor(_contentType: string): undefined {}
+
   jsonld(): Promise<null> {
     return Promise.resolve(null);
   }
@@ -636,13 +676,14 @@ export class Action<
   }
 
   define<
+    Auth extends AuthState = AuthState,
     Term extends string = string,
     Spec extends ActionSpec = ActionSpec,
-  >(args: DefineArgs<Term, Spec>): DefinedAction<State, Term, Spec> {
-    return new DefinedAction<State, Term, Spec>(
+  >(args: DefineArgs<Term, Spec>): DefinedAction<State, Auth, Term, Spec> {
+    return new DefinedAction<State, Auth, Term, Spec>(
       args.typeDef,
       args.spec ?? {} as Spec,
-      this.#meta as unknown as ActionMeta<State, Spec>,
+      this.#meta as unknown as ActionMeta<State, Auth, Spec>,
     );
   }
   
@@ -665,18 +706,23 @@ export class Action<
     });
   }
 
+  perform(req: Request): Promise<Response> {
+    return this.#meta.perform(req);
+  }
+
 }
 
 export class PreAction<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
 > implements
   Applicable<Action>,
-  Handleable<State>
+  Handleable<State, Auth>
 {
-  #meta: ActionMeta<State>;
+  #meta: ActionMeta<State, Auth>;
 
   constructor(
-    meta: ActionMeta<State>,
+    meta: ActionMeta<State, Auth>,
   ) {
     this.#meta = meta;
   }
@@ -690,18 +736,18 @@ export class PreAction<
   define<
     Term extends string = string,
     Spec extends ActionSpec = ActionSpec,
-  >(args: DefineArgs<Term, Spec>): DefinedAction<State, Term, Spec> {
-    return new DefinedAction<State, Term, Spec>(
+  >(args: DefineArgs<Term, Spec>): DefinedAction<State, Auth, Term, Spec> {
+    return new DefinedAction<State, Auth, Term, Spec>(
       args.typeDef,
       args.spec,
-      this.#meta as unknown as ActionMeta<State, Spec>,
+      this.#meta as unknown as ActionMeta<State, Auth, 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(
+  handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State, Auth>): FinalizedAction<State, Auth>;
+  handle(args: HandlerObj<State>): FinalizedAction<State, Auth>;
+  handle(arg1: unknown, arg2?: unknown): FinalizedAction<State, Auth> {
+    return FinalizedAction.fromHandlers<State, Auth>(
       null,
       {},
       this.#meta,
@@ -713,29 +759,30 @@ export class PreAction<
 
 export class Endpoint<
   State extends ContextState = ContextState,
+  Auth extends AuthState = AuthState,
 > implements
   Applicable<Action>,
-  Handleable<State>
+  Handleable<State, Auth>
 {
-  #meta: ActionMeta<State>;
+  #meta: ActionMeta<State, Auth>;
 
   constructor(
-    meta: ActionMeta<State>,
+    meta: ActionMeta<State, Auth>,
   ) {
     this.#meta = meta;
   }
   
-  hint(hints: HintArgs): Endpoint<State> {
+  hint(hints: HintArgs): Endpoint<State, Auth> {
     this.#meta.hints.push(hints);
 
     return this;
   }
 
-  compress(): Endpoint<State> {
+  compress(): Endpoint<State, Auth> {
     return this;
   }
   
-  cache(args: CacheInstanceArgs) {
+  cache(args: CacheInstanceArgs): Endpoint<State, Auth> {
     this.#meta.cache.push(args);
 
     return this;
@@ -745,30 +792,30 @@ export class Endpoint<
     return this;
   }
 
-  use(): Action<State> {
-    return new Action<State>(this.#meta);
+  use(): Action<State, Auth> {
+    return new Action<State, Auth>(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: DefineArgs<Term, Spec>): DefinedAction<State, Auth, Term, Spec> {
+    return new DefinedAction<State, Auth, Term, Spec>(
       args.typeDef,
       args.spec,
-      this.#meta as ActionMeta<State, Spec>,
+      this.#meta as ActionMeta<State, Auth, Spec>,
     );
   }
 
-  handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State>): FinalizedAction<State>;
-  handle(args: HandlerObj<State>): FinalizedAction<State>;
-  handle(arg1: unknown, arg2?: unknown): FinalizedAction<State> {
+  handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State>): FinalizedAction<State, Auth>;
+  handle(args: HandlerObj<State, Auth>): FinalizedAction<State, Auth>;
+  handle(arg1: unknown, arg2?: unknown): FinalizedAction<State, Auth> {
     return FinalizedAction.fromHandlers(
       undefined,
       {},
       this.#meta,
       arg1 as string | string[],
-      arg2 as HandlerFn<State>,
+      arg2 as HandlerFn<State, Auth>,
     );
   }
 }
@@ -782,14 +829,27 @@ export class ActionAuth<
     this.#meta = meta;
   }
 
-  public(): Endpoint<State> {
+  public<
+    Auth extends AuthState = AuthState,
+  >(authMiddleware?: AuthMiddleware<Auth>): Endpoint<State, Auth> {
+    if (authMiddleware != null && typeof authMiddleware !== 'function')
+      throw new Error('Public action given invalid auth middleware');
+
     this.#meta.public = true;
-    
-    return new Endpoint(this.#meta);
+    this.#meta.auth = authMiddleware;
+
+    return new Endpoint(this.#meta as ActionMeta<State, Auth>);
   }
 
-  private(): Endpoint<State> {
-    return new Endpoint(this.#meta);
+  private<
+    Auth extends AuthState = AuthState,
+  >(authMiddleware: AuthMiddleware<Auth>): Endpoint<State, Auth> {
+    if (typeof authMiddleware !== 'function')
+      throw new Error('Private action given invalid auth middleware');
+
+    this.#meta.auth = authMiddleware;
+
+    return new Endpoint(this.#meta as ActionMeta<State, Auth>);
   }
 }