@occultist/occultist 0.0.9 → 0.0.11

package/dist/actions/context.d.ts

@@ -1,4 +1,4 @@
-import type { CacheOperation, HandlerDefinition } from "../mod.ts";
+import type { CacheOperation, HandlerDefinition, StaticAsset } from "../mod.ts";
 import type { Registry } from "../registry.ts";
 import type { ActionPayload, ActionSpec, ContextState, ParsedIRIValues } from "./spec.ts";
 import type { AuthState, ImplementedAction } from "./types.ts";
@@ -84,5 +84,14 @@ export declare class Context<State extends ContextState = ContextState, Auth ext
     set status(status: number);
     get body(): undefined | ResponseBody;
     set body(body: ResponseBody);
+    /**
+     * Returns the public facing URL of a static asset using its
+     * static file alias.
+     *
+     * @param assetAlias The alias of the static asset.
+     * @param cspDirective A directive to add the asset to when generating CSP headers.
+     * @returns The public facing URL of the static asset.
+     */
+    useAsset(assetAlias: string, cspDirective?: string): StaticAsset | undefined;
     get [Symbol.toStringTag](): string;
 }

package/dist/actions/context.js

@@ -3,6 +3,8 @@ class EditableContext {
     etag;
     status;
     body;
+    staticAssets = new Map();
+    cspDirectives;
 }
 ;
 /**
@@ -121,6 +123,33 @@ export class Context {
     set body(body) {
         this.#editable.body = body;
     }
+    /**
+     * Returns the public facing URL of a static asset using its
+     * static file alias.
+     *
+     * @param assetAlias The alias of the static asset.
+     * @param cspDirective A directive to add the asset to when generating CSP headers.
+     * @returns The public facing URL of the static asset.
+     */
+    useAsset(assetAlias, cspDirective) {
+        const staticAlias = assetAlias.split('/')[0];
+        const extension = this.registry.getStaticExtension(staticAlias);
+        if (extension == null)
+            return;
+        const asset = extension.getAsset(assetAlias);
+        if (asset == null)
+            return;
+        this.#editable.staticAssets.set(asset.alias, asset);
+        if (typeof cspDirective === 'string' && cspDirective != null) {
+            if (!this.#editable.cspDirectives.has(cspDirective)) {
+                this.#editable.cspDirectives.set(cspDirective, [asset.alias]);
+            }
+            else {
+                this.#editable.cspDirectives.get(cspDirective).push(asset.alias);
+            }
+        }
+        return asset;
+    }
     get [Symbol.toStringTag]() {
         return `action=${this.action.name} method=${this.method} contentType=${this.contentType}`;
     }

package/dist/registry.d.ts

@@ -7,7 +7,7 @@ import { IncomingMessage, type ServerResponse } from "node:http";
 import type { Merge } from "./actions/spec.ts";
 import type { ContextState, Middleware } from "./actions/spec.ts";
 import { type CacheOperationResult } from "./mod.ts";
-import type { Extension } from "./types.ts";
+import type { Extension, StaticExtension } from "./types.ts";
 export interface Callable<State extends ContextState = ContextState> {
     method(method: string, name: string, path: string): ActionAuth<State>;
 }
@@ -249,6 +249,13 @@ export declare class Registry<State extends ContextState = ContextState> impleme
      * @returns A NodeJS server response instance.
      */
     handleRequest(req: IncomingMessage, res: ServerResponse): Promise<ServerResponse>;
+    /**
+     * Retrieves a static extension by one of the static aliases it uses.
+     *
+     * @param staticAlias A static alias used to create paths to files served
+     *   by the static extension.
+     */
+    getStaticExtension(staticAlias: string): StaticExtension | undefined;
     /**
      * Registers an Occultist extension. This is usually done
      * by extensions when they are created.

package/dist/registry.js

@@ -123,6 +123,7 @@ export class Registry {
     #actions = null;
     #handlers = null;
     #extensions = [];
+    #staticExtensions = new Map();
     constructor(args) {
         const url = new URL(args.rootIRI);
         this.#rootIRI = args.rootIRI;
@@ -500,6 +501,15 @@ export class Registry {
             return res;
         }
     }
+    /**
+     * Retrieves a static extension by one of the static aliases it uses.
+     *
+     * @param staticAlias A static alias used to create paths to files served
+     *   by the static extension.
+     */
+    getStaticExtension(staticAlias) {
+        return this.#staticExtensions.get(staticAlias);
+    }
     /**
      * Registers an Occultist extension. This is usually done
      * by extensions when they are created.
@@ -507,6 +517,17 @@ export class Registry {
      * @param The Occultist extension to register.
      */
     registerExtension(extension) {
+        let staticAlias;
+        if (typeof extension.getAsset === 'function' &&
+            Array.isArray(extension.staticAliases)) {
+            for (let i = 0; i < extension.staticAliases.length; i++) {
+                staticAlias = extension.staticAliases[i];
+                if (this.#staticExtensions.has(staticAlias)) {
+                    throw new Error(`Static alias '${staticAlias}' already used by other extension`);
+                }
+                this.#staticExtensions.set(staticAlias, extension);
+            }
+        }
         this.#extensions.push(extension);
     }
     /**

package/dist/types.d.ts

@@ -1,10 +1,50 @@
+export interface StaticAsset {
+    alias: string;
+    contentType: string;
+    url: string;
+    integrity?: string;
+}
 export interface StaticContext {
     link(alias: string, as: string): string;
 }
 export interface Extension {
+    /**
+     * The name of the extension.
+     */
     name: string;
+    /**
+     * Setup method which can perform async setup tasks
+     * and report status via a readable stream.
+     */
     setup?(): ReadableStream;
-    createStaticContext?(): StaticContext;
+    /**
+     * Retrieves a static assets from the extension.
+     *
+     * @param assetAlias The alias for the asset.
+     */
+    getAsset?(assetAlias: string): StaticAsset | undefined;
+    /**
+     * Root level aliases the extension uses to identify
+     * the assets it manages.
+     */
+    staticAliases?: string[];
+}
+export interface StaticExtension {
+    /**
+     * The name of the extension.
+     */
+    name: string;
+    /**
+     * Root level aliases the extension uses to identify
+     * assets it manages.
+     */
+    staticAliases: string[];
+    /**
+     * Retrieves a static assets from the extension.
+     *
+     * @param assetAlias The alias for the asset.
+     */
+    getAsset(assetAlias: string): StaticAsset | undefined;
 }
 export type ProblemDetailsParam = {
     name: string;

package/dist/types.js

@@ -1,2 +1,3 @@
 ;
+;
 export {};

package/lib/actions/context.ts

@@ -1,4 +1,4 @@
-import type {CacheOperation, HandlerDefinition} from "../mod.ts";
+import type {CacheOperation, HandlerDefinition, StaticAsset} from "../mod.ts";
 import type {Registry} from "../registry.ts";
 import type {ActionPayload, ActionSpec, ContextState, ParsedIRIValues} from "./spec.ts";
 import type {AuthState, ImplementedAction} from "./types.ts";
@@ -10,6 +10,8 @@ class EditableContext {
   etag?: string;
   status?: number;
   body?: ResponseBody;
+  staticAssets: Map<string, StaticAsset> = new Map();
+  cspDirectives: Map<string, string[]>;
 };
 
 export type CacheContextArgs<
@@ -187,6 +189,37 @@ export class Context<
     this.#editable.body = body;
   }
 
+  /**
+   * Returns the public facing URL of a static asset using its
+   * static file alias.
+   *
+   * @param assetAlias The alias of the static asset.
+   * @param cspDirective A directive to add the asset to when generating CSP headers.
+   * @returns The public facing URL of the static asset.
+   */
+  useAsset(assetAlias: string, cspDirective?: string): StaticAsset | undefined {
+    const staticAlias = assetAlias.split('/')[0];
+    const extension = this.registry.getStaticExtension(staticAlias);
+
+    if (extension == null) return;
+
+    const asset = extension.getAsset(assetAlias);
+
+    if (asset == null) return;
+
+    this.#editable.staticAssets.set(asset.alias, asset);
+
+    if (typeof cspDirective === 'string' && cspDirective != null) {
+      if (!this.#editable.cspDirectives.has(cspDirective)) {
+        this.#editable.cspDirectives.set(cspDirective, [asset.alias]);
+      } else {
+        this.#editable.cspDirectives.get(cspDirective).push(asset.alias);
+      }
+    }
+
+    return asset;
+  }
+
   get [Symbol.toStringTag]() {
     return `action=${this.action.name} method=${this.method} contentType=${this.contentType}`;
   }

package/lib/registry.ts

@@ -11,7 +11,7 @@ import type { ContextState, Middleware } from "./actions/spec.ts";
 import {ProblemDetailsError} from "./errors.ts"
 import {WrappedRequest} from "./request.ts";
 import {type CacheOperationResult} from "./mod.ts";
-import type {Extension} from "./types.ts";
+import type {Extension, StaticExtension} from "./types.ts";
 
 
 export interface Callable<
@@ -189,6 +189,7 @@ export class Registry<
   #actions: ImplementedAction[] | null = null;
   #handlers: HandlerDefinition[] | null = null;
   #extensions: Extension[] = [];
+  #staticExtensions: Map<string, StaticExtension> = new Map();
 
   constructor(args: RegistryArgs) {
     const url = new URL(args.rootIRI);
@@ -733,6 +734,16 @@ export class Registry<
     }
   }
 
+  /**
+   * Retrieves a static extension by one of the static aliases it uses.
+   *
+   * @param staticAlias A static alias used to create paths to files served
+   *   by the static extension.
+   */
+  getStaticExtension(staticAlias: string): StaticExtension | undefined {
+    return this.#staticExtensions.get(staticAlias);
+  }
+
   /**
    * Registers an Occultist extension. This is usually done
    * by extensions when they are created.
@@ -740,6 +751,22 @@ export class Registry<
    * @param The Occultist extension to register.
    */
   registerExtension(extension: Extension): void {
+    let staticAlias: string;
+    if (
+      typeof extension.getAsset === 'function' &&
+      Array.isArray(extension.staticAliases)
+    ) {
+      for (let i = 0; i < extension.staticAliases.length; i++) {
+        staticAlias = extension.staticAliases[i];
+
+        if (this.#staticExtensions.has(staticAlias)) {
+          throw new Error(`Static alias '${staticAlias}' already used by other extension`);
+        }
+
+        this.#staticExtensions.set(staticAlias, extension as StaticExtension);
+      }
+    }
+
     this.#extensions.push(extension);
   }
 

package/lib/types.ts

@@ -1,14 +1,65 @@
 
+export interface StaticAsset {
+  alias: string;
+  contentType: string;
+  url: string;
+  integrity?: string;
+};
+
 export interface StaticContext {
   link(alias: string, as: string): string;
 }
 
 export interface Extension {
+
+  /**
+   * The name of the extension.
+   */
   name: string;
+
+  /**
+   * Setup method which can perform async setup tasks
+   * and report status via a readable stream.
+   */
   setup?(): ReadableStream;
-  createStaticContext?(): StaticContext;
+
+  /**
+   * Retrieves a static assets from the extension.
+   *
+   * @param assetAlias The alias for the asset.
+   */
+  getAsset?(assetAlias: string): StaticAsset | undefined;
+
+  /**
+   * Root level aliases the extension uses to identify
+   * the assets it manages.
+   */
+  staticAliases?: string[];
+
 };
 
+export interface StaticExtension {
+
+  /**
+   * The name of the extension.
+   */
+  name: string;
+
+  /**
+   * Root level aliases the extension uses to identify
+   * assets it manages.
+   */
+  staticAliases: string[];
+
+  /**
+   * Retrieves a static assets from the extension.
+   *
+   * @param assetAlias The alias for the asset.
+   */
+  getAsset(assetAlias: string): StaticAsset | undefined;
+
+}
+
 export type ProblemDetailsParam = {
   name: string;
   reason: string;

package/package.json

@@ -35,7 +35,7 @@
     "jsonld": "^9.0.0",
     "typescript": "^5.9.3"
   },
-  "version": "0.0.9",
+  "version": "0.0.11",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "node --test"