@occultist/occultist 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthew Quinn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# Occultist
+
+**Occultist** is an under-development, Koa-inspired backend web framework for Node or Deno,
+adding structure to less-supported HTTP features.
+
+
+## Features
+
+### Auth middleware
+All endpoints require that they are marked public or private simplifying future
+auditing processes. When marked public they and can optionally have auth middleware
+provided to identify the requester. Private endpoints require a auth middleware is
+provided. 
+
+### Request url and body input processing
+Request bodies, route parameters and query string values can be fully described to
+Occultist allowing it to unpack multipart/form-data, application/json requests 
+producing a single typescript typed `ctx.payload` object with all inputs merged together.
+Failed requests automatically support responding with
+[application/problem+json](https://www.rfc-editor.org/rfc/rfc9457.html) responses.
+
+### Content negotiation
+Endpoints can have multiple handlers defined responding with different content
+types. Occultist automatically routes the request to the correct handler based
+off the request's accept header, or the first handler if no accept handler is set.
+
+### Caching middleware
+Use caching providers to store representations using the provided auth information
+request's URL's parameters and resulting content type provided by the other special
+case middlewares.
+
+### Advanced features
+Occultist is being built to complement the also under-development frontend framework 
+[Octiron](https://github.com/occultist-dev/octiron) which is built to consume JSON-ld
+APIs and build complex forms using actions in the [schema.org/Action](https://schema.org/Action)
+style. This relationship will be better explained as the two frameworks stablize.
+
+
+Occultist is in flux at the moment but you can try it now. Endpoints can be created
+with most url and body processing features working for application/json requests and
+content negotiation works for the response's content. The auth and cache features
+described here are yet to be implemented.
+
+
+## Installation
+```
+npm install @occultist/occultist
+deno add jsr:@occultist/occultist
+```
+
+
+## Example
+```typescript
+import { Registry } from '@occultist/occultist';
+
+// TODO
+const auth = new AuthProvider();
+// TODO
+const cache = new CacheProvider();
+
+const registry = new Registry({
+  root: 'https://example.com',
+});
+
+registry.http.get('list-cats', '/cats')
+  // Endpoints are marked public and can optionally have
+  // auth middleware identify the requester, or they are
+  // marked private and the auth check is required.
+  .public(auth.optional())
+  
+  // resulting representation cache keys would vary based
+  // on the an auth key that is unique to the user that the above
+  // middleware provides, other parameters can further vary the
+  // cache and control http cache headers.
+  .cache(cache.etag())
+
+  // define handlers to respond with supported content types.
+  .handle('text/html', (ctx) => {
+    ctx.body = `
+      <!doctype>
+      <html>
+        <body>
+          <h1>Hello, World!</h1>
+        </body>
+      </html>
+    `;
+  })
+  .handle('application/json', (ctx) => {
+    ctx.body = `{
+      "message": "Hello, World!",
+    }`;
+  });
+
+// The same method and path combination can be re-used for endpoints
+// which have different middleware requirements. The accept header
+// can be used by requests to pull an alternative representation.
+registry.http.get('get-cat', '/cats')
+  .public()
+  .handle('application/xml', (ctx) => { ... })
+
+registry.http.post('create-cat', '/cats')
+  .private(auth.hasPermission('create-cats'))
+  // With a body payload defined any requests with
+  // application/json or multipart/form-data bodies
+  // are automatically pre-processed into the `ctx.payload`.
+  .define({
+    spec: {
+      name: {
+        dataType: 'string',
+        minValueLength: 2,
+        valueRequired: true,
+      },
+      hasStripes: {
+        dataType: 'boolean',
+        valueRequired: true,
+      },
+      image: {
+        // you would want to use form-data for a large file upload
+        // but data uris can be sent via json
+        dataType: 'blob',
+      },
+    },
+  })
+  .handle('text/html', async (ctx) => {
+    const cat = await storage.createCat({
+      name: ctx.payload.name,
+      hasStripes: ctx.payload.hasStripes,
+      image: ctx.payload.image,
+    });
+    ctx.status = 303;
+    ctx.headers.set('Location', `https://example.com/cats/${cat.id}`);
+  });
+
+// required before requests are handled
+registry.finalize();
+
+const server = createServer();
+
+// for Node, Deno and probably Bun.
+server.on('request', (req, res) => registry.handleRequest(req, res));
+server.listen(3000);
+```
+
+## Advanced features

package/dist/accept.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Creates a content type cache usually from the set of content type
+ * options supported by an action or action set.
+ */
+export declare class ContentTypeCache {
+    default: string;
+    set: Set<string>;
+    map: Map<string, string>;
+    contentTypes: string[];
+    constructor(contentTypes: string[]);
+    get [Symbol.toStringTag](): string;
+}
+/**
+ * This accept object is created from a request before any content negotiation
+ * begins allowing all subsequent checks to re-use the same caches header values.
+ *
+ * @todo Implement support for all accept headers.
+ *
+ * @param accept - The value of the request's accept header.
+ * @param acceptLanguage - The value of the request's accept-language header.
+ * @param acceptEncoding - The value of the request's accept-encoding header.
+ */
+export declare class Accept {
+    #private;
+    acceptRe: RegExp;
+    accept: string[];
+    acceptCache: Set<string>;
+    constructor(accept: string | null, _acceptLanguage: string | null, _acceptEncoding: string | null);
+    /**
+     * Creates an accept instance from a request or response instance
+     */
+    static from(req: Request): Accept;
+    debug(): string;
+    /**
+     * Negotiates against the cached set of content type options.
+     *
+     * @param contentType Content type cache built for an action.
+     */
+    negotiate(contentType: ContentTypeCache): null | string;
+    get [Symbol.toStringTag](): string;
+}

package/dist/accept.js

@@ -0,0 +1,110 @@
+/**
+ * Creates a content type cache usually from the set of content type
+ * options supported by an action or action set.
+ */
+export class ContentTypeCache {
+    default;
+    set;
+    map = new Map();
+    contentTypes;
+    constructor(contentTypes) {
+        this.default = contentTypes[0];
+        this.contentTypes = contentTypes;
+        this.set = new Set(contentTypes);
+        this.set.add('*/*');
+        this.map.set('*/*', contentTypes[0]);
+        for (let index = 0; index < contentTypes.length; index++) {
+            const contentType = contentTypes[index];
+            const type = contentType.replace(/[^\/]*$/, '*');
+            this.map.set(contentType, contentType);
+            if (!this.map.has(type)) {
+                this.set.add(type);
+                this.map.set(type, contentType);
+            }
+        }
+    }
+    get [Symbol.toStringTag]() {
+        return `[ContentTypeCache ${this.contentTypes.join(' ')}]`;
+    }
+}
+/**
+ * This accept object is created from a request before any content negotiation
+ * begins allowing all subsequent checks to re-use the same caches header values.
+ *
+ * @todo Implement support for all accept headers.
+ *
+ * @param accept - The value of the request's accept header.
+ * @param acceptLanguage - The value of the request's accept-language header.
+ * @param acceptEncoding - The value of the request's accept-encoding header.
+ */
+export class Accept {
+    acceptRe = /(?<ct>[^,;\s]+)(;\s?q=(?<q>(\d(\.\d+)|(.\d))))?/g;
+    accept = [];
+    acceptCache = new Set();
+    //#acceptLanguage: string[] = [];
+    //#acceptLanguageCache: Set<string> = new Set();
+    //#acceptEncoding: string[] = [];
+    //#acceptEncodingCache: Set<string> = new Set();
+    constructor(accept, _acceptLanguage, _acceptEncoding) {
+        [this.accept, this.acceptCache] = this.#process(accept);
+        //[this.#acceptLanguage, this.#acceptLanguageCache] = this.#process(acceptLanguage);
+        //[this.#acceptEncoding, this.#acceptEncodingCache] = this.#process(acceptEncoding);
+    }
+    /**
+     * Creates an accept instance from a request or response instance
+     */
+    static from(req) {
+        const accept = req.headers.get('Accept');
+        const acceptLanguage = req.headers.get('Accept-Language');
+        const acceptEncoding = req.headers.get('Accept-Encoding');
+        console.log('ACCEPT', accept);
+        return new Accept(accept, acceptLanguage, acceptEncoding);
+    }
+    debug() {
+        return this.accept.join(' ');
+    }
+    /**
+     * Negotiates against the cached set of content type options.
+     *
+     * @param contentType Content type cache built for an action.
+     */
+    negotiate(contentType) {
+        if (this.accept.length === 0) {
+            return contentType.default;
+        }
+        // TODO: check might be over-optimizing.
+        const intersection = this.acceptCache.intersection(contentType.set);
+        if (intersection.size === 0) {
+            return null;
+        }
+        for (let index = 0; index < this.accept.length; index++) {
+            const match = contentType.map.get(this.accept[index]);
+            if (match != null) {
+                return match;
+            }
+        }
+        return null;
+    }
+    #process(header) {
+        if (header == null) {
+            return [[], new Set('*/*')];
+        }
+        let match;
+        const items = [];
+        const cache = new Set();
+        while ((match = this.acceptRe.exec(header))) {
+            const ct = match.groups?.ct;
+            const q = Number(match.groups?.q ?? 1);
+            cache.add(ct);
+            items.push({ ct, q });
+        }
+        items.sort((a, b) => b.q - a.q);
+        return [
+            items.map(({ ct }) => ct),
+            cache,
+        ];
+    }
+    get [Symbol.toStringTag]() {
+        return `[Accept ${this.accept.join(' ')}]`;
+    }
+}

package/dist/accept.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/accept.test.js

@@ -0,0 +1,44 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { Accept, ContentTypeCache } from "./accept.js";
+const cache = new ContentTypeCache([
+    'text/html',
+    'application/ld+json',
+    'application/json',
+]);
+test('Matches with no accepts header', () => {
+    const accept = Accept.from(new Request('https://example.com'));
+    assert(accept.negotiate(cache) === 'text/html');
+});
+test('Matches with specific accepts header', () => {
+    const accept = Accept.from(new Request('https://example.com', {
+        headers: {
+            accept: 'application/ld+json',
+        },
+    }));
+    assert(accept.negotiate(cache) === 'application/ld+json');
+});
+test('Matches with glob header', () => {
+    const accept = Accept.from(new Request('https://example.com', {
+        headers: {
+            accept: '*/*',
+        },
+    }));
+    assert(accept.negotiate(cache) === 'text/html');
+});
+test('Matches with glob subtype header', () => {
+    const accept = Accept.from(new Request('https://example.com', {
+        headers: {
+            accept: 'application/*',
+        },
+    }));
+    assert(accept.negotiate(cache) === 'application/ld+json');
+});
+test('Matches q prioritizing in header', () => {
+    const accept = Accept.from(new Request('https://example.com', {
+        headers: {
+            accept: 'text/html; q=0.5, application/json; q=1, text/cvs; q=.7',
+        },
+    }));
+    assert(accept.negotiate(cache) === 'application/json');
+});

package/dist/action.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/action.test.js

@@ -0,0 +1 @@
+export {};

package/dist/actions/actionSets.d.ts

@@ -0,0 +1,23 @@
+import { type Accept } from "../accept.js";
+import type { ActionMeta } from "./meta.js";
+import type { ImplementedAction } from "./types.js";
+export type UnsupportedContentTypeMatch = {
+    type: 'unsupported-content-type';
+    contentTypes: string[];
+};
+export type ActionAcceptMatch = {
+    type: 'match';
+    action: ImplementedAction;
+    contentType?: string;
+    language?: string;
+    encoding?: string;
+};
+export type ActionMatchResult = UnsupportedContentTypeMatch | ActionAcceptMatch;
+/**
+ * A set of actions grouped by having equal methods and equivilent paths.
+ */
+export declare class ActionSet {
+    #private;
+    constructor(rootIRI: string, method: string, path: string, meta: ActionMeta[]);
+    matches(method: string, path: string, accept: Accept): null | ActionMatchResult;
+}

package/dist/actions/actionSets.js

@@ -0,0 +1,49 @@
+import { ContentTypeCache } from "../accept.js";
+import { makeURLPattern } from "../utils/makeURLPattern.js";
+/**
+ * A set of actions grouped by having equal methods and equivilent paths.
+ */
+export class ActionSet {
+    #rootIRI;
+    #method;
+    #urlPattern;
+    #contentTypeActionMap;
+    #ctc;
+    constructor(rootIRI, method, path, meta) {
+        this.#rootIRI = rootIRI;
+        this.#method = method;
+        this.#urlPattern = makeURLPattern(path, rootIRI);
+        [this.#contentTypeActionMap, this.#ctc] = this.#process(meta);
+    }
+    matches(method, path, accept) {
+        if (method !== this.#method) {
+            return null;
+        }
+        else if (!this.#urlPattern.test(path, this.#rootIRI)) {
+            return null;
+        }
+        const contentType = accept.negotiate(this.#ctc);
+        const action = this.#contentTypeActionMap.get(contentType);
+        if (contentType != null && action != null) {
+            return {
+                type: 'match',
+                action,
+                contentType,
+            };
+        }
+        return null;
+    }
+    #process(meta) {
+        const contentTypes = [];
+        const contentTypeActionMap = new Map();
+        for (let i = 0; i < meta.length; i++) {
+            const action = meta[i].action;
+            for (let j = 0; j < action.contentTypes.length; j++) {
+                const contentType = action.contentTypes[j];
+                contentTypes.push(contentType);
+                contentTypeActionMap.set(contentType, action);
+            }
+        }
+        return [contentTypeActionMap, new ContentTypeCache(contentTypes)];
+    }
+}

package/dist/actions/actions.d.ts

@@ -0,0 +1,163 @@
+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 { type ActionMeta } from "./meta.js";
+import type { ActionSpec, ContextState } from "./spec.js";
+import type { 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;
+};
+/**
+ * A handler definition which can be pulled from a registry, scope or action
+ * after an action is defined.
+ */
+export declare 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);
+    get [Symbol.toStringTag](): string;
+}
+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 declare class FinalizedAction<State extends ContextState = ContextState, Spec extends ActionSpec = ActionSpec> implements Handleable<State, Spec>, ImplementedAction<State, Spec> {
+    #private;
+    constructor(typeDef: TypeDef | undefined, spec: Spec, meta: ActionMeta<State, Spec>, handlerArgs: HandlerObj<State, Spec>);
+    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 toJSONLD(action: ImplementedAction, scope: Scope): Promise<JSONObject | null>;
+    get public(): boolean;
+    get method(): string;
+    get term(): string | undefined;
+    get type(): string | undefined;
+    get typeDef(): TypeDef | undefined;
+    get name(): string;
+    get template(): string;
+    get pattern(): URLPattern;
+    get spec(): Spec;
+    get scope(): Scope | undefined;
+    get registry(): Registry;
+    get handlers(): HandlerDefinition<State, Spec>[];
+    get contentTypes(): string[];
+    get context(): JSONObject;
+    url(): string;
+    jsonld(): Promise<JSONObject | null>;
+    jsonldPartial(): {
+        '@type': string;
+        '@id': string;
+    } | null;
+    handle(contentType: string | string[], handler: HandlerFn<State, Spec> | HandlerValue): FinalizedAction<State, Spec>;
+    handle(args: HandlerObj<State, Spec>): FinalizedAction<State, Spec>;
+    handleRequest(args: HandleRequestArgs): Promise<ResponseTypes>;
+}
+export interface Applicable<ActionType> {
+    use(): ActionType;
+}
+export declare 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> {
+    #private;
+    constructor(typeDef: TypeDef | undefined, spec: Spec, meta: ActionMeta<State, Spec>);
+    get public(): boolean;
+    get method(): string;
+    get term(): string | undefined;
+    get type(): string | undefined;
+    get typeDef(): TypeDef | undefined;
+    get name(): string;
+    get template(): string;
+    get pattern(): URLPattern;
+    get path(): string;
+    get spec(): Spec;
+    get scope(): Scope | undefined;
+    get registry(): Registry;
+    get handlers(): HandlerDefinition<State, Spec>[];
+    get contentTypes(): string[];
+    url(): string;
+    get context(): JSONLDContext;
+    jsonld(): Promise<JSONObject | null>;
+    jsonldPartial(): {
+        '@type': string;
+        '@id': string;
+    } | null;
+    /**
+     * 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>;
+    meta(): DefinedAction<State, string, Spec>;
+    use(): DefinedAction<State, string, Spec>;
+    handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State, Spec>): FinalizedAction<State, Spec>;
+    handle(args: HandlerObj<State, Spec>): FinalizedAction<State, Spec>;
+    handleRequest(args: HandleRequestArgs): Promise<ResponseTypes>;
+}
+export declare class Action<State extends ContextState = ContextState> implements Applicable<Action>, Handleable<State>, ImplementedAction<State> {
+    #private;
+    constructor(meta: ActionMeta<State>);
+    get public(): boolean;
+    get method(): string;
+    get term(): string | undefined;
+    get type(): string | undefined;
+    get typeDef(): TypeDef | undefined;
+    get name(): string;
+    get template(): string;
+    get pattern(): URLPattern;
+    get path(): string;
+    get spec(): ActionSpec;
+    get scope(): Scope | undefined;
+    get registry(): Registry;
+    get handlers(): HandlerDefinition[];
+    get contentTypes(): string[];
+    get context(): JSONObject;
+    url(): string;
+    jsonld(): Promise<null>;
+    jsonldPartial(): {
+        '@type': string;
+        '@id': string;
+    } | null;
+    use(): Action<State>;
+    define<Term extends string = string, Spec extends ActionSpec = ActionSpec>(args: DefineArgs<Term, Spec>): DefinedAction<State, Term, Spec>;
+    handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State>): FinalizedAction<State>;
+    handle(args: HandlerObj<State>): FinalizedAction<State>;
+    handleRequest(args: HandleRequestArgs): Promise<ResponseTypes>;
+}
+export declare class PreAction<State extends ContextState = ContextState> implements Applicable<Action>, Handleable<State> {
+    #private;
+    constructor(meta: ActionMeta<State>);
+    use(): Action<State>;
+    define<Term extends string = string, Spec extends ActionSpec = ActionSpec>(args: DefineArgs<Term, Spec>): DefinedAction<State, Term, Spec>;
+    handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State>): FinalizedAction<State>;
+    handle(args: HandlerObj<State>): FinalizedAction<State>;
+}
+export declare class Endpoint<State extends ContextState = ContextState> implements Applicable<Action>, Handleable<State> {
+    #private;
+    constructor(meta: ActionMeta<State>);
+    hint(hints: HintArgs): Endpoint<State>;
+    compress(): Endpoint<State>;
+    cache(args: CacheInstanceArgs): this;
+    etag(): this;
+    use(): Action<State>;
+    define<Term extends string = string, Spec extends ActionSpec = ActionSpec>(args: DefineArgs<Term, Spec>): DefinedAction<State, Term, Spec>;
+    handle(contentType: string | string[], handler: HandlerValue | HandlerFn<State>): FinalizedAction<State>;
+    handle(args: HandlerObj<State>): FinalizedAction<State>;
+}
+export declare class ActionAuth<State extends ContextState = ContextState> {
+    #private;
+    constructor(meta: ActionMeta<State>);
+    public(): Endpoint<State>;
+    private(): Endpoint<State>;
+}