@occultist/occultist 0.0.1

package/lib/cache/etag.ts

@@ -0,0 +1,106 @@
+
+export class EtagConditions {
+
+  headers: Headers;
+  
+  constructor(headers: Headers) {
+    this.headers = headers;
+  }
+
+  /**
+   * Returns true if the representation is not modified based of
+   * conditional headers and the value of the current representation's
+   * etag. True results should result in a 304 response.
+   *
+   * @param representationEtag - The current etag value for this representation.
+   */
+  public isNotModified(representationEtag?: string): boolean {
+    if (this.headers.has('If-Match')) {
+      return this.ifMatch(representationEtag);
+    } else if (this.headers.has('If-None-Match')) {
+      return !this.ifNoneMatch(representationEtag);
+    }
+
+    return false;
+  }
+
+  public ifMatch(
+    representationEtag?: string,
+  ): boolean {
+    let etag: string;
+    const header = this.headers.get('If-Match');
+
+    if (header == null) {
+      return true;
+    } else if (header.trim() === '*') {
+      return representationEtag != null;
+    }
+
+    const etags = header.split?.(',');
+
+    if (etags.length === 0) {
+      return true;
+    } else if (representationEtag == null) {
+      return false;
+    }
+
+    for (let i = 0; i < etags.length; i++) {
+      etag = etags[i].trim();
+
+      // If-Match ignores weak etags
+      if (etag.startsWith('W\/')) {
+        continue;
+      } else if (etag === representationEtag) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  public ifNoneMatch(
+    representationEtag?: string,
+  ): boolean {
+    let etag: string;
+    const header = this.headers.get('If-None-Match');
+
+    if (header == null || representationEtag == null) {
+      return true;
+    }
+
+    const etags = header.split?.(',');
+
+    if (etags.length === 0) {
+      return true;
+    }
+
+    if (etags[0] === '*') {
+      return representationEtag == null;
+    }
+
+    for (let i = 0; i < etags.length; i++) {
+      etag = etags[i].trim();
+
+      if (!etag.startsWith('W\/')) {
+        continue;
+      } else if (etag === representationEtag) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  public ifModifiedSince(): never {
+    throw new Error('Not implemented');
+  }
+  
+  public ifUnmodifiedSince(): never {
+    throw new Error('Not implemented');
+  }
+
+  public ifRange(): never {
+    throw new Error('Not implemented');
+  }
+
+}

package/lib/cache/memory.ts

@@ -0,0 +1,52 @@
+import type {CacheDetails, CacheHitHandle, CacheMeta, CacheStorage, CacheMissHandle} from './types.js';
+
+
+export class InMemoryCacheMeta implements CacheMeta {
+  #details: Map<string, CacheDetails> = new Map();
+
+  async get(key: string): Promise<CacheHitHandle| CacheMissHandle> {
+    const details = this.#details.get(key);
+    async function set(details: CacheDetails) {
+      this.#details.set(key, details);
+    }
+
+    if (details == null) {
+      return {
+        type: 'cache-miss',
+        set,
+      };
+    }
+    
+    return {
+      ...details,
+      type: 'cache-hit',
+      set,
+    };
+  }
+
+  async set(key: string, details: CacheDetails) {
+    this.#details.set(key, details);
+  }
+
+}
+
+export class InMemoryCacheStorage implements CacheStorage {
+  #cache: Map<string, Blob> = new Map();
+
+  get(key: string): Blob {
+    const value = this.#cache.get(key);
+
+    return value as Blob;
+  }
+
+  set(key: string, value: Blob): void {
+    this.#cache.set(key, value);
+  }
+
+  invalidate(key: string): void {
+    this.#cache.delete(key);
+  }
+
+}
+
+

package/lib/cache/types.ts

@@ -0,0 +1,240 @@
+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/lib/errors.ts

@@ -0,0 +1,66 @@
+import {ProblemDetails} from "./types.js";
+
+// https://datatracker.ietf.org/doc/html/rfc9457
+export class ProblemDetailsError extends Error {
+  status: number;
+  problemDetails: ProblemDetails;
+  parentErr?: unknown;
+
+  constructor(
+    status: number,
+    problemDetails: string | ProblemDetails,
+    parentErr?: unknown,
+  ) {
+    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: string = '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: string) {
+    super(400, { title, type: 'invalid-param' });
+  }
+}

package/lib/jsonld.ts

@@ -0,0 +1,67 @@
+import type { ShallowMerge } from "./merge.js";
+
+// Union of numbers within our depth limit
+export type RecursiveDigit = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+
+// Array where each value is one greater than its index in the array
+export type RecursiveNextDigit = [1, 2, 3, 4, 5, 6, 7, 'STOP'];
+
+// Type to get the number from the index in the array
+export type RecursiveIncrement<T> = T extends RecursiveDigit
+  ? RecursiveNextDigit[T]
+  : 'STOP';
+
+// deno-lint-ignore no-explicit-any
+export type EmptyObject = Pick<{ [key: string]: any }, ''>;
+
+// deno-lint-ignore no-explicit-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 };
+
+
+// https://w3c.github.io/json-ld-syntax/#syntax-tokens-and-keywords
+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>;
+
+// deno-lint-ignore no-explicit-any
+export type TypeDef<Term extends string = any, Type extends string = any> = {
+  type: Type;
+  term: Term;
+  contextDefinition?: ContextDefinition;
+};

package/lib/makeTypeDefs.ts

@@ -0,0 +1,138 @@
+import { joinPaths } from "./utils/joinPaths.js"
+import type { ContextDefinition, ContextDefinitionContainer, JSONLDContext, TypeDef } from "./jsonld.js";
+import type { Context } from "./actions/context.js";
+import { isPopulatedObject } from "./utils/isPopulatedObject.js";
+import { isPopulatedString } from "./utils/isPopulatedString.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 function makeTypeDef<Term extends string, Schema extends string>(
+  term: Term,
+  type: Schema,
+): TypeDef<Term, `${Schema}${Term}`>;
+
+export function makeTypeDef<Term extends string, Type extends string>(
+  args: MakeTypeDefArgsFromType<Term, Type>,
+): TypeDef<Term, Type>;
+
+export function makeTypeDef<Term extends string, Schema extends string>(
+  args: MakeTypeDefArgsFromSchema<Term, Schema>,
+): TypeDef<Term, `${Schema}${Term}`>;
+
+export function makeTypeDef<Term extends string, TypeOrSchema extends string>(
+  arg1: Term | MakeTypeDefArgs<Term, TypeOrSchema>,
+  arg2?: TypeOrSchema,
+) {
+  let contextDefinition: ContextDefinition = {};
+  let protect: boolean = false;
+  let args: MakeTypeDefArgs<Term, TypeOrSchema>;
+
+  if (typeof arg1 === 'string') {
+    args = {
+      term: arg1,
+      schema: arg2 as TypeOrSchema,
+    };
+  } 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 as JSONLDContext;
+    }
+
+    if (protect) {
+      contextDefinition['@protected'] = true;
+    }
+
+    if (isPopulatedString(args.schema)) {
+      return {
+        term: args.term,
+        type: joinPaths(args.schema, args.term),
+        contextDefinition,
+      } as TypeDef<Term, `${TypeOrSchema}${Term}`>;
+    }
+
+    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,
+    } as TypeDef<Term, `${TypeOrSchema}${Term}`>;
+  }
+
+  return {
+    term: args.term,
+    type: args.type,
+    contextDefinition,
+  };
+}
+
+export function makeTypeDefs<Term extends string, TD extends TypeDef<Term>>(
+  typeDefs: Readonly<Array<TD>>,
+): { [TypeDef in TD as TypeDef['term']]: TypeDef } {
+  type TypeDefs = { [TypeDef in TD as TypeDef['term']]: TypeDef };
+  const result = typeDefs.reduce(
+    (acc, typeDef) => ({
+      ...acc,
+      [typeDef.term]: typeDef,
+    }),
+    {},
+  );
+
+  return result as TypeDefs;
+}