@occultist/occultist 0.0.1

package/dist/cache/memory.js

@@ -0,0 +1,36 @@
+export class InMemoryCacheMeta {
+    #details = new Map();
+    async get(key) {
+        const details = this.#details.get(key);
+        async function set(details) {
+            this.#details.set(key, details);
+        }
+        if (details == null) {
+            return {
+                type: 'cache-miss',
+                set,
+            };
+        }
+        return {
+            ...details,
+            type: 'cache-hit',
+            set,
+        };
+    }
+    async set(key, details) {
+        this.#details.set(key, details);
+    }
+}
+export class InMemoryCacheStorage {
+    #cache = new Map();
+    get(key) {
+        const value = this.#cache.get(key);
+        return value;
+    }
+    set(key, value) {
+        this.#cache.set(key, value);
+    }
+    invalidate(key) {
+        this.#cache.delete(key);
+    }
+}

package/dist/cache/types.d.ts

@@ -0,0 +1,175 @@
+import { ImplementedAction } from "../actions/types.js";
+import { CacheContext } from "../mod.js";
+export type CacheStrategyType = 'http' | 'etag' | 'store';
+export interface CacheEntryDescriptor {
+    contentType: string;
+    action: ImplementedAction;
+    request: Request;
+    args: CacheInstanceArgs;
+}
+export type CacheWhenFn = (ctx: CacheContext) => boolean;
+export type CacheRuleArgs = {
+    /**
+     * A version which should increment every when a new release
+     * causes the existing cache to become stale.
+     */
+    version?: number;
+    lock?: boolean;
+    /**
+     * Defaults to varying on the authorization header
+     * when authenticated.
+     */
+    vary?: string;
+    varyOnAuth?: boolean;
+    varyOnCapabilities?: string | string[];
+    /**
+     * Defaults to false when a querystring is present
+     * or the request is authenticated.
+     *
+     * @default 'public-no-query'
+     */
+    when?: 'always' | 'public' | 'private' | 'no-query' | 'public-no-query' | 'private-no-query' | CacheWhenFn;
+};
+export type CacheControlArgs = {
+    private?: boolean;
+    public?: true;
+    noCache?: true;
+    noStore?: true;
+    mustRevalidate?: true;
+    mustUndestand?: true;
+    noTransform?: true;
+    immutable?: true;
+    proxyRevalidate?: true;
+    expires?: () => number | Date;
+    maxAge?: number | Date | (() => number | Date);
+    etag?: string;
+};
+export type CacheHTTPArgs = {
+    strategy: 'http';
+    strong?: undefined;
+    fromRequest?: undefined;
+} & CacheRuleArgs & CacheControlArgs;
+export type CacheHTTPInstanceArgs = CacheHTTPArgs & {
+    strategy: 'http';
+    cache: CacheBuilder;
+};
+export type CacheETagArgs = {
+    strategy: 'etag';
+    strong?: boolean;
+    fromRequest?: boolean;
+    etag?: undefined;
+} & CacheRuleArgs & Omit<CacheControlArgs, 'etag'>;
+export type CacheETagInstanceArgs = CacheETagArgs & {
+    stratey: 'etag';
+    cache: CacheBuilder;
+};
+export type CacheStoreArgs = {
+    strategy: 'store';
+    strong?: boolean;
+    fromRequest?: boolean;
+    etag?: undefined;
+} & CacheRuleArgs & Omit<CacheControlArgs, 'etag'>;
+export type CacheStoreInstanceArgs = CacheStoreArgs & {
+    strategy: 'store';
+    cache: CacheBuilder;
+};
+export type CacheInstanceArgs = CacheHTTPInstanceArgs | CacheETagInstanceArgs | CacheStoreInstanceArgs;
+export type CacheDetails = {
+    key: string;
+    iri: string;
+    status?: number;
+    hasContent: boolean;
+    authKey: string;
+    etag: string;
+    headers: Headers;
+    contentType: string;
+    contentLength?: number;
+    contentEncoding?: string;
+    contentLanguage?: string;
+    contentRange?: string;
+};
+export type CacheHitHandle = CacheDetails & {
+    type: 'cache-hit';
+    set(details: CacheDetails): Promise<void>;
+};
+export type CacheMissHandle = {
+    type: 'cache-miss';
+    set(details: CacheDetails): Promise<void>;
+};
+export type LockedCacheMissHandle = {
+    type: 'locked-cache-miss';
+    set(details: CacheDetails): Promise<void>;
+    release(): Promise<void>;
+};
+/**
+ * The cache meta knows how to query a storage for current freshness
+ * information on a cache entry without querying the data itself.
+ *
+ * Meta information might be stored in a separate data store to the
+ * cached response bodies. If supported by the storage, the representation
+ * can be locked for update preventing other requests for the same
+ * resource from proceeding until the cached representation is created.
+ */
+export interface CacheMeta {
+    /**
+     * Sets the cache details for a representation.
+     *
+     * @param key       A unique key for this representation.
+     * @param details   The cache details.
+     */
+    set(key: string, details: CacheDetails): void | Promise<void>;
+    /**
+     * Retrieves the cache details of a representation.
+     *
+     * @param key       A unique key for this representation.
+     */
+    get(key: string): CacheHitHandle | CacheMissHandle | Promise<CacheHitHandle | CacheMissHandle>;
+    /**
+     * Retrieves the cache details of a representation and takes a lock
+     * for update if the representation is not current.
+     *
+     * Any other requests for this representation will wait for the request
+     * holding the lock to populate the cache before proceeding.
+     *
+     * @param key   A unique key for this representation.
+     */
+    getOrLock?(key: string): Promise<CacheHitHandle | LockedCacheMissHandle>;
+}
+export interface UpstreamCache {
+    /**
+     * Pushes a representation to the upstream cache.
+     */
+    push(args: {
+        url: string;
+        headers: Headers;
+        data: Blob;
+    }): Promise<void>;
+    /**
+     * Invalidates a representation in the upstream cache.
+     */
+    invalidate(url: string): Promise<void>;
+}
+export interface CacheStorage {
+    /**
+     * Retrieves a cache entry.
+     */
+    get(key: string): Blob | Promise<Blob>;
+    /**
+     * Sets a cache entry.
+     */
+    set(key: string, data: Blob): void | Promise<void>;
+    /**
+     * Invalidates a cache entry.
+     */
+    invalidate(key: string): void | Promise<void>;
+}
+export interface CacheBuilder {
+    meta: CacheMeta;
+    storage: CacheStorage;
+    upstream: UpstreamCache | undefined;
+    http(args?: CacheHTTPArgs): CacheInstanceArgs;
+    etag(args?: CacheETagArgs): CacheInstanceArgs;
+    store(args?: CacheStoreArgs): CacheInstanceArgs;
+    invalidate?(request: Request): Promise<void>;
+    push?(request: Request): Promise<void>;
+}

package/dist/cache/types.js

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

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+import { ProblemDetails } from "./types.js";
+export declare class ProblemDetailsError extends Error {
+    status: number;
+    problemDetails: ProblemDetails;
+    parentErr?: unknown;
+    constructor(status: number, problemDetails: string | ProblemDetails, parentErr?: unknown);
+    toContent(contentType?: string): string;
+}
+export declare class InvalidActionParamsError extends ProblemDetailsError {
+    constructor(title: string);
+}

package/dist/errors.js

@@ -0,0 +1,54 @@
+// https://datatracker.ietf.org/doc/html/rfc9457
+export class ProblemDetailsError extends Error {
+    status;
+    problemDetails;
+    parentErr;
+    constructor(status, problemDetails, parentErr) {
+        const message = typeof problemDetails === 'string'
+            ? problemDetails
+            : problemDetails.title;
+        super(message);
+        this.status = status;
+        this.parentErr = parentErr;
+        if (typeof problemDetails === 'string') {
+            this.problemDetails = { title: problemDetails };
+        }
+        else {
+            this.problemDetails = problemDetails;
+        }
+    }
+    toContent(contentType = 'application/ld+json') {
+        if (contentType === 'text/html') {
+            return `
+        <!doctype html>
+        <html lang="en">
+        <head>
+          <title>${this.problemDetails.title}</title>
+        </head>
+        <body>
+          <h1>${this.problemDetails.title}</h1>
+
+          <dl>
+            ${this.problemDetails?.errors?.map((error) => {
+                return `
+                <dt>
+                  <code>${error.name}</code>
+                </dt>
+                <dd>
+                  ${error.reason}
+                </dd>
+              `;
+            })}
+          </dl>
+        </body>
+        </html>
+      `;
+        }
+        return JSON.stringify(this.problemDetails);
+    }
+}
+export class InvalidActionParamsError extends ProblemDetailsError {
+    constructor(title) {
+        super(400, { title, type: 'invalid-param' });
+    }
+}

package/dist/jsonld.d.ts

@@ -0,0 +1,43 @@
+import type { ShallowMerge } from "./merge.js";
+export type RecursiveDigit = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+export type RecursiveNextDigit = [1, 2, 3, 4, 5, 6, 7, 'STOP'];
+export type RecursiveIncrement<T> = T extends RecursiveDigit ? RecursiveNextDigit[T] : 'STOP';
+export type EmptyObject = Pick<{
+    [key: string]: any;
+}, ''>;
+export type GuardType<T> = T extends (value: any) => value is infer U ? U : never;
+export type JSONPrimitive = string | number | boolean | null | undefined;
+export type JSONValue = JSONPrimitive | JSONObject | JSONArray;
+export type JSONObject = {
+    [member: string]: JSONValue;
+};
+export interface JSONArray extends Array<JSONValue> {
+}
+export type OrArray<T> = T | Array<T>;
+export type Merge<T1 extends object, T2 extends object> = ShallowMerge<T1, T2>;
+export type IRI = string;
+export type IRIObject = {
+    '@id': IRI;
+};
+export type Aliases = Record<string, string>;
+export type ContextVersion = 1.1;
+export type ContextDefinitionType = '@id';
+export type ContextDefinitionContainer = '@list' | '@set';
+export type ContextDefinition = {
+    '@id'?: string;
+    '@type'?: ContextDefinitionType;
+    '@container'?: ContextDefinitionContainer;
+    '@context'?: JSONLDContext;
+    '@protected'?: boolean;
+};
+export type JSONLDContext = {
+    '@version'?: ContextVersion;
+    '@base'?: string;
+    '@protected'?: boolean;
+    '@vocab'?: string;
+} & Record<string, string | ContextDefinition>;
+export type TypeDef<Term extends string = any, Type extends string = any> = {
+    type: Type;
+    term: Term;
+    contextDefinition?: ContextDefinition;
+};

package/dist/jsonld.js

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

package/dist/makeTypeDefs.d.ts

@@ -0,0 +1,27 @@
+import type { ContextDefinitionContainer, TypeDef } from "./jsonld.js";
+import type { Context } from "./actions/context.js";
+export type MakeTypeDefArgsFromType<Term extends string, Type extends string> = {
+    term: Term;
+    type: Type;
+    schema?: undefined;
+    isIRI?: boolean;
+    protect?: boolean;
+    container?: ContextDefinitionContainer;
+    context?: Context;
+};
+export type MakeTypeDefArgsFromSchema<Term extends string, Schema extends string> = {
+    term: Term;
+    schema: Schema;
+    type?: undefined;
+    isIRI?: boolean;
+    protect?: boolean;
+    container?: ContextDefinitionContainer;
+    context?: Context;
+};
+export type MakeTypeDefArgs<A extends string, B extends string> = MakeTypeDefArgsFromType<A, B> | MakeTypeDefArgsFromSchema<A, B>;
+export declare function makeTypeDef<Term extends string, Schema extends string>(term: Term, type: Schema): TypeDef<Term, `${Schema}${Term}`>;
+export declare function makeTypeDef<Term extends string, Type extends string>(args: MakeTypeDefArgsFromType<Term, Type>): TypeDef<Term, Type>;
+export declare function makeTypeDef<Term extends string, Schema extends string>(args: MakeTypeDefArgsFromSchema<Term, Schema>): TypeDef<Term, `${Schema}${Term}`>;
+export declare function makeTypeDefs<Term extends string, TD extends TypeDef<Term>>(typeDefs: Readonly<Array<TD>>): {
+    [TypeDef in TD as TypeDef['term']]: TypeDef;
+};

package/dist/makeTypeDefs.js

@@ -0,0 +1,70 @@
+import { joinPaths } from "./utils/joinPaths.js";
+import { isPopulatedObject } from "./utils/isPopulatedObject.js";
+import { isPopulatedString } from "./utils/isPopulatedString.js";
+export function makeTypeDef(arg1, arg2) {
+    let contextDefinition = {};
+    let protect = false;
+    let args;
+    if (typeof arg1 === 'string') {
+        args = {
+            term: arg1,
+            schema: arg2,
+        };
+    }
+    else {
+        args = arg1;
+        if (typeof arg1.protect === 'boolean') {
+            protect = arg1.protect;
+        }
+    }
+    if (args.isIRI || isPopulatedString(args.container) ||
+        isPopulatedObject(args.context)) {
+        contextDefinition = {};
+        if (args.isIRI) {
+            contextDefinition['@type'] = '@id';
+        }
+        if (isPopulatedString(args.container)) {
+            contextDefinition['@container'] = args.container;
+        }
+        if (isPopulatedObject(args.context)) {
+            contextDefinition['@context'] = args.context;
+        }
+        if (protect) {
+            contextDefinition['@protected'] = true;
+        }
+        if (isPopulatedString(args.schema)) {
+            return {
+                term: args.term,
+                type: joinPaths(args.schema, args.term),
+                contextDefinition,
+            };
+        }
+        return {
+            term: args.term,
+            type: args.type,
+            contextDefinition,
+        };
+    }
+    if (protect) {
+        contextDefinition = { '@protected': true };
+    }
+    if (isPopulatedString(args.schema)) {
+        return {
+            term: args.term,
+            type: joinPaths(args.schema, args.term),
+            contextDefinition,
+        };
+    }
+    return {
+        term: args.term,
+        type: args.type,
+        contextDefinition,
+    };
+}
+export function makeTypeDefs(typeDefs) {
+    const result = typeDefs.reduce((acc, typeDef) => ({
+        ...acc,
+        [typeDef.term]: typeDef,
+    }), {});
+    return result;
+}

package/dist/merge.d.ts

@@ -0,0 +1,61 @@
+export type ShallowMerge<T1 extends object, T2 extends object> = {
+    [K in keyof T1 & keyof T2]: T1[K] | T2[K];
+} & ({
+    [K in Exclude<keyof T1, keyof T2>]: T1[K];
+}) & ({
+    [K in Exclude<keyof T2, keyof T1>]: T2[K];
+});
+export type DeepMergeTwoTypes<T, U> = [
+    T,
+    U
+] extends [any[], any[]] ? Zip_DeepMergeTwoTypes<T, U> : [T, U] extends [{
+    [key: string]: unknown;
+}, {
+    [key: string]: unknown;
+}] ? MergeTwoObjects<T, U> : T | U;
+export type DeepMerge<T1, T2> = (T1 extends object ? (T2 extends object ? (MergeToOne<({
+    [K in (keyof T2 & keyof T1 & RequiredKeys<T1 | T2>)]: DeepMerge<T1[K], T2[K]>;
+} & {
+    [K in (keyof T2 & keyof T1 & OptionalKeys<T1 | T2>)]?: DeepMerge<T1[K], T2[K]>;
+} & {
+    [K in Exclude<RequiredKeys<T1>, keyof T2>]: T1[K];
+} & {
+    [K in Exclude<OptionalKeys<T1>, keyof T2>]?: T1[K];
+} & {
+    [K in Exclude<RequiredKeys<T2>, keyof T1>]: T2[K];
+} & {
+    [K in Exclude<OptionalKeys<T2>, keyof T1>]?: T2[K];
+})>) : (T1 extends object ? T2 : T1 | T2)) : (T2 extends object ? T1 : T1 | T2));
+type Head<T> = T extends [infer I, ...infer _Rest] ? I : never;
+type Tail<T> = T extends [infer _I, ...infer Rest] ? Rest : never;
+type Zip_DeepMergeTwoTypes<T, U> = T extends [] ? U : U extends [] ? T : [
+    DeepMergeTwoTypes<Head<T>, Head<U>>,
+    ...Zip_DeepMergeTwoTypes<Tail<T>, Tail<U>>
+];
+/**
+ * Take two objects T and U and create the new one with uniq keys for T a U objectI
+ * helper generic for `DeepMergeTwoTypes`
+ */
+type GetObjDifferentKeys<T, U, T0 = Omit<T, keyof U> & Omit<U, keyof T>, T1 = {
+    [K in keyof T0]: T0[K];
+}> = T1;
+/**
+ * Take two objects T and U and create the new one with the same objects keys
+ * helper generic for `DeepMergeTwoTypes`
+ */
+type GetObjSameKeys<T, U> = Omit<T | U, keyof GetObjDifferentKeys<T, U>>;
+type MergeTwoObjects<T, U, T0 = Partial<GetObjDifferentKeys<T, U>> & {
+    [K in keyof GetObjSameKeys<T, U>]: DeepMergeTwoTypes<T[K], U[K]>;
+}, T1 = {
+    [K in keyof T0]: T0[K];
+}> = T1;
+type MergeToOne<T> = (T extends object ? {
+    [K in keyof T]: (K extends RequiredKeys<T> ? Exclude<T[K], undefined> : T[K]);
+} : never);
+type RequiredKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+type OptionalKeys<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
+}[keyof T];
+export {};

package/dist/merge.js

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

package/dist/mod.d.ts

@@ -0,0 +1,14 @@
+export * from './cache/types.js';
+export * from './cache/cache.js';
+export * from './cache/memory.js';
+export * from './actions/types.js';
+export * from './actions/meta.js';
+export * from './actions/spec.js';
+export * from './actions/context.js';
+export * from './actions/path.js';
+export * from './actions/actions.js';
+export * from './actions/actionSets.js';
+export * from './registry.js';
+export * from './makeTypeDefs.js';
+export * from './utils/joinPaths.js';
+export * from './utils/contextBuilder.js';

package/dist/mod.js

@@ -0,0 +1,14 @@
+export * from './cache/types.js';
+export * from './cache/cache.js';
+export * from './cache/memory.js';
+export * from './actions/types.js';
+export * from './actions/meta.js';
+export * from './actions/spec.js';
+export * from './actions/context.js';
+export * from './actions/path.js';
+export * from './actions/actions.js';
+export * from './actions/actionSets.js';
+export * from './registry.js';
+export * from './makeTypeDefs.js';
+export * from './utils/joinPaths.js';
+export * from './utils/contextBuilder.js';

package/dist/processAction.d.ts

@@ -0,0 +1,15 @@
+import type { ImplementedAction } from "./actions/types.js";
+import type { ActionPayload, ActionSpec, ContextState, ParsedIRIValues } from "./actions/spec.js";
+export type ProcessActionArgs<State extends ContextState = ContextState, Spec extends ActionSpec<ContextState> = ActionSpec<ContextState>> = {
+    iri: string;
+    req: Request;
+    spec: Spec;
+    state: State;
+    action: ImplementedAction<State, Spec>;
+};
+export type ProcessActionResult<Spec extends ActionSpec<ContextState> = ActionSpec<ContextState>> = {
+    params: ParsedIRIValues;
+    query: ParsedIRIValues;
+    payload: ActionPayload<Spec>;
+};
+export declare function processAction<State extends ContextState = ContextState, Spec extends ActionSpec<ContextState> = ActionSpec<ContextState>>({ iri, req, spec, state, action, }: ProcessActionArgs<State, Spec>): Promise<ProcessActionResult<Spec>>;