@occultist/occultist 0.0.8 → 0.0.10

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/mod.d.ts

@@ -1,3 +1,4 @@
+export * from './types.ts';
 export * from './cache/types.ts';
 export * from './cache/cache.ts';
 export * from './cache/memory.ts';

package/dist/mod.js

@@ -1,3 +1,4 @@
+export * from "./types.js";
 export * from "./cache/types.js";
 export * from "./cache/cache.js";
 export * from "./cache/memory.js";

package/dist/registry.d.ts

@@ -7,6 +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, StaticExtension } from "./types.ts";
 export interface Callable<State extends ContextState = ContextState> {
     method(method: string, name: string, path: string): ActionAuth<State>;
 }
@@ -248,6 +249,25 @@ 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.
+     *
+     * @param The Occultist extension to register.
+     */
+    registerExtension(extension: Extension): void;
+    /**
+     * Must be called after all Occultist extensions have been registered.
+     * When some of the extensions have async setup tasks.
+     */
+    setupExtensions(): Promise<void>;
     addEventListener(type: RegistryEvents, callback: EventListener): void;
     removeEventListener(type: RegistryEvents, callback: EventListener): void;
 }

package/dist/registry.js

@@ -122,6 +122,8 @@ export class Registry {
     #middleware = [];
     #actions = null;
     #handlers = null;
+    #extensions = [];
+    #staticExtensions = new Map();
     constructor(args) {
         const url = new URL(args.rootIRI);
         this.#rootIRI = args.rootIRI;
@@ -499,6 +501,52 @@ 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.
+     *
+     * @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);
+    }
+    /**
+     * Must be called after all Occultist extensions have been registered.
+     * When some of the extensions have async setup tasks.
+     */
+    async setupExtensions() {
+        const setupStreams = [];
+        for (let i = 0; i < this.#extensions.length; i++) {
+            if (typeof this.#extensions[i].setup === 'function') {
+                setupStreams.push(this.#extensions[i].setup());
+            }
+        }
+        for (let i = 0; i < setupStreams.length; i++) {
+            for await (const message of setupStreams[i]) {
+                console.log(message);
+            }
+        }
+    }
     addEventListener(type, callback) {
         this.#eventTarget.addEventListener(type, callback);
     }

package/dist/types.d.ts

@@ -1,3 +1,35 @@
+export interface StaticAsset {
+    alias: string;
+    contentType: string;
+    url: string;
+    integrity?: string;
+}
+export interface StaticContext {
+    link(alias: string, as: string): string;
+}
+export interface Extension {
+    name: string;
+    setup?(): ReadableStream;
+    getAsset?(): StaticAsset | undefined;
+    staticAliases?: string[];
+}
+export interface StaticExtension {
+    /**
+     * The name of the static 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/dist/types.js

@@ -1 +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/mod.ts

@@ -1,3 +1,4 @@
+export * from './types.ts';
 export * from './cache/types.ts';
 export * from './cache/cache.ts';
 export * from './cache/memory.ts';

package/lib/registry.ts

@@ -11,6 +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, StaticExtension} from "./types.ts";
 
 
 export interface Callable<
@@ -187,6 +188,8 @@ export class Registry<
   #middleware: Middleware[] = [];
   #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);
@@ -731,6 +734,62 @@ 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.
+   *
+   * @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);
+  }
+
+  /**
+   * Must be called after all Occultist extensions have been registered.
+   * When some of the extensions have async setup tasks.
+   */
+  async setupExtensions(): Promise<void> {
+    const setupStreams: ReadableStream[] = [];
+
+    for (let i = 0; i < this.#extensions.length; i++) {
+      if (typeof this.#extensions[i].setup === 'function') {
+        setupStreams.push(this.#extensions[i].setup());
+      }
+    }
+
+    for (let i = 0; i < setupStreams.length; i++) {
+      for await (const message of setupStreams[i]) {
+        console.log(message);
+      }
+    }
+  }
+
   addEventListener(type: RegistryEvents, callback: EventListener) {
     this.#eventTarget.addEventListener(type, callback);
   };

package/lib/types.ts

@@ -1,3 +1,44 @@
+
+export interface StaticAsset {
+  alias: string;
+  contentType: string;
+  url: string;
+  integrity?: string;
+};
+
+export interface StaticContext {
+  link(alias: string, as: string): string;
+}
+
+export interface Extension {
+  name: string;
+  setup?(): ReadableStream;
+  getAsset?(): StaticAsset | undefined;
+  staticAliases?: string[];
+};
+
+export interface StaticExtension {
+
+  /**
+   * The name of the static 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.8",
+  "version": "0.0.10",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "node --test"