@occultist/occultist 0.0.1

package/lib/request.ts

@@ -0,0 +1,153 @@
+import {IncomingMessage} from "node:http";
+import {Readable} from "node:stream";
+import {normalizeURL} from "./utils/normalizeURL.js";
+
+
+export class WrappedRequest implements Request {
+
+  #url: string;
+  #req: Request | IncomingMessage;
+  #stream: ReadableStream;
+  #bodyUsed: boolean = false;
+  #headers: Headers = new Headers();
+
+  constructor(rootIRI: string, req: Request | IncomingMessage) {
+    this.#req = req;
+    this.#url = normalizeURL(rootIRI, req.url);
+
+    if (req instanceof Request) {
+      this.#stream = req.body;
+      this.#headers = req.headers;
+    } else {
+      this.#stream = Readable.toWeb(req) as ReadableStream;
+    
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (Array.isArray(value)) {
+          for (let i = 0; i < value.length; i++) {
+            this.#headers.append(key, value[i]);
+          }
+        } else {
+          this.#headers.set(key, value);
+        }
+      }
+    }
+  }
+
+  get body(): ReadableStream {
+    if (this.#bodyUsed) {
+      throw new Error('Body has already been consumed');
+    }
+
+    this.#bodyUsed = true;
+    return this.#stream;
+  }
+
+  arrayBuffer(): Promise<ArrayBuffer> {
+    return new Response(this.body).arrayBuffer();
+  }
+
+  blob(): Promise<Blob> {
+    return new Response(this.body).blob();
+  }
+
+  bytes(): Promise<Uint8Array<ArrayBuffer>> {
+    return new Response(this.body).bytes();
+  }
+
+  clone(): Request {
+    if (this.#bodyUsed) {
+      throw new Error('Body has already been consumed');
+    }
+    
+    const [a, b] = this.#stream.tee();
+
+    this.#stream = a;
+
+    return new Request(this.url, {
+      ...this,
+      body: b,
+    });
+  }
+
+  formData(): Promise<FormData> {
+    return new Response(this.body).formData();
+  }
+
+  json(): Promise<unknown> {
+    return new Response(this.body).json();
+  }
+
+  text(): Promise<string> {
+    return new Response(this.body).text();
+  }
+
+  get bodyUsed(): boolean {
+    return this.#bodyUsed;
+  }
+
+  get cache(): RequestCache {
+    return 'default';
+  }
+
+  get credentials(): RequestCredentials {
+    return 'same-origin';
+  }
+
+  get destination(): RequestDestination {
+    return '';
+  }
+
+  get duplex(): undefined | 'half' {
+    return undefined;
+  }
+
+  get headers(): Headers {
+    return this.#headers;
+  }
+
+  get integrity(): string {
+    return '';
+  }
+  
+  get isHistoryNavigation(): boolean {
+    return false;
+  }
+  
+  get keepalive(): boolean {
+    return false;
+  }
+
+  get method(): string {
+    return this.#req.method ?? 'GET';
+  }
+
+  get mode(): RequestMode {
+    return 'cors';
+  }
+
+  get redirect(): RequestRedirect {
+    return 'follow';
+  }
+
+  get referrer(): string {
+    return this.#headers.get('Referrer') ?? 'no-referrer';
+  }
+
+  get referrerPolicy(): ReferrerPolicy {
+    const referrerPolicy = this.#headers.get('Referrer-Policy');
+
+    if (Array.isArray(referrerPolicy)) {
+      return referrerPolicy[0] as ReferrerPolicy ?? '';
+    }
+
+    return referrerPolicy as ReferrerPolicy ?? '';
+  }
+
+  get signal(): AbortSignal | undefined {
+    return undefined;
+  }
+
+  get url(): string {
+    return this.#url;
+  }
+}

package/lib/scopes.test.ts

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { Registry } from "./registry.js";
+import { makeTypeDef, makeTypeDefs } from "./makeTypeDefs.js";
+
+
+const typeDefs = makeTypeDefs([
+  makeTypeDef('GetThing', 'https://schema.example.com/'),
+  makeTypeDef('name', 'https://schema.org/'),
+  makeTypeDef('description', 'https://schema.org/'),
+]);
+
+const registry = new Registry({
+  rootIRI: 'https://example.com',
+});
+
+const scope = registry.scope('/actions')
+  .public();
+
+scope.http.get('get-thing', '/thing')
+  .public()
+  .define({
+    typeDef: typeDefs.GetThing,
+    spec: {
+      name: {
+        typeDef: typeDefs.name,
+        valueMinLength: 3,
+        valueRequired: true,
+      },
+      description: {
+        type: 'https://schema.org/description',
+        valueRequired: false,
+      },
+    },
+  });
+
+registry.finalize();
+
+test('It responds with actions partials as a jsonld type map', async () => {
+  const res = await registry.handleRequest(
+    new Request('https://example.com/actions'),
+  )
+  const body = await res.json();
+
+  assert.deepEqual(body[typeDefs.GetThing.type], {
+    '@type': typeDefs.GetThing.type,
+    '@id': 'https://example.com/actions/get-thing',
+  });
+});
+
+test('It responds with actions partials as a jsonld type map', async () => {
+  const res = await registry.handleRequest(
+    new Request('https://example.com/actions/get-thing'),
+  )
+  const body = await res.json();
+  
+  // compacted representation is returned
+  assert.equal(body['@id'], 'https://example.com/actions/get-thing');
+  assert.equal(body['@type'], typeDefs.GetThing.term);
+  assert.deepEqual(body[`${typeDefs.name.term}-input`], {
+    '@type': 'https://schema.org/PropertyValueSpecification',
+    valueRequired: true,
+    valueMinLength: 3,
+  });
+  assert.deepEqual(body[`${typeDefs.description.term}-input`], {
+    '@type': 'https://schema.org/PropertyValueSpecification',
+    valueRequired: false,
+  });
+});
+

package/lib/scopes.ts

@@ -0,0 +1,178 @@
+import { joinPaths } from "./utils/joinPaths.js";
+import { ActionAuth, HandlerDefinition } from "./actions/actions.js";
+import { ActionMeta } from "./actions/meta.js";
+import type { ContextState } from "./actions/spec.js";
+import type { ImplementedAction } from "./actions/types.js";
+import type { HTTPWriter } from "./actions/writer.js";
+import { type Callable, HTTP, type Registry } from './registry.js';
+
+
+export type MetaPropatator = (meta: ActionMeta) => void;
+
+export type ScopeArgs = {
+  path: string;
+  serverTiming?: boolean;
+  registry: Registry;
+  writer: HTTPWriter;
+  propergateMeta: MetaPropatator;
+}
+
+
+export class Scope<
+  State extends ContextState = ContextState,
+> implements Callable<State> {
+  #path: string;
+  #serverTiming: boolean = false;
+  #registry: Registry;
+  #writer: HTTPWriter;
+  #http: HTTP<State>;
+  #children: Array<ActionMeta> = [];
+  #public: boolean = true;
+  #propergateMeta: (meta: ActionMeta) => void;
+  
+  constructor({
+    path,
+    serverTiming,
+    registry,
+    writer,
+    propergateMeta,
+  }: ScopeArgs) {
+    this.#path = path;
+    this.#serverTiming = serverTiming;
+    this.#registry = registry;
+    this.#writer = writer;
+    this.#http = new HTTP<State>(this);
+    this.#propergateMeta = propergateMeta;
+  }
+
+  get path(): string {
+    return this.#path;
+  }
+
+  get registry(): Registry {
+    return this.#registry;
+  }
+
+  get http(): HTTP<State> {
+    return this.#http;
+  }
+
+  get actions(): Array<ImplementedAction> {
+    return this.#children
+      .filter((meta) => {
+        if (meta.action == null) {
+          console.warn(`Action ${meta.method}: ${meta.path} not fully implemented before processing`);
+        }
+
+        return meta.action != null;
+      })
+      .map((meta) => meta.action) as Array<ImplementedAction>;
+  }
+
+  get handlers(): HandlerDefinition[] {
+    return this.actions.flatMap((action) => action.handlers);
+  }
+
+  public(): Scope<State> {
+    this.#public = true;
+
+    return this;
+  }
+
+  private(): Scope<State> {
+    this.#public = false;
+
+    return this;
+  }
+
+  /**
+   * Creates any HTTP method.
+   *
+   * @param method The HTTP method.
+   * @param name   Name for the action being produced.
+   * @param path   Path the action responds to.
+   */
+  method(method: string, name: string, path: string): ActionAuth<State> {
+    const meta = new ActionMeta<State>(
+      this.#registry.rootIRI,
+      method.toUpperCase(),
+      name,
+      path,
+      this.#registry,
+      this.#writer,
+      this,
+    );
+
+    meta.serverTiming = this.#serverTiming;
+
+    this.#children.push(meta);
+    this.#propergateMeta(meta);
+    
+    return new ActionAuth<State>(meta);
+  }
+  
+  url(): string {
+    return joinPaths(this.#registry.rootIRI, this.#path);
+  }
+
+  finalize(): void {
+    const partials = {
+      '@id': this.url(),
+      '@container': '@type',
+    };
+
+    for (let index = 0; index < this.#children.length; index++) {
+      const meta = this.#children[index];
+      const action = meta.action;
+
+      if (action == null || action.type == null) {
+        continue;
+      }
+
+      const partial = action.jsonldPartial();
+
+      if (partial == null) {
+        continue;
+      }
+
+      partials[partial['@type']] = partial;
+    }
+
+    if (this.#public) {
+      this.#registry.http.get('scope', this.#path)
+        .public()
+        .handle('application/ld+json', (ctx) => {
+          ctx.body = JSON.stringify(partials);
+        });
+    } else {
+      this.#registry.http.get('scope', this.#path)
+        .public()
+        .handle('application/ld+json', (ctx) => {
+           ctx.body = JSON.stringify(partials);
+        });
+    }
+    
+    for (let index = 0; index < this.#children.length; index++) {
+      const action = this.#children[index].action;
+
+      if (action == null || action.type == null) {
+        continue;
+      }
+
+      if (this.#public) {
+        this.#registry.http.get('scope-action', joinPaths(this.url(), action.name))
+          .public()
+          .handle('application/ld+json', async (ctx) => {
+            ctx.body = JSON.stringify(await action.jsonld());
+          });
+      } else {
+        this.#registry.http.get('scope-action', joinPaths(this.url(), action.name))
+          .private()
+          .handle('application/ld+json', async (ctx) => {
+            ctx.body = JSON.stringify(await action.jsonld());
+          });
+      }
+    }
+  }
+}
+

package/lib/transformers/fileTransformer.ts

@@ -0,0 +1,10 @@
+
+export async function fileTransformer(value: File | string): Promise<File | Blob> {
+  if (typeof value === 'string') {
+    return fetch(value)
+      .then((res) => res.blob())
+      .catch(() => Promise.reject('Invalid data url'))
+  }
+
+  return value;
+}

package/lib/types.ts

@@ -0,0 +1,13 @@
+export type ProblemDetailsParam = {
+  name: string;
+  reason: string;
+  pointer?: string;
+};
+
+export type ProblemDetails = {
+  title: string;
+  type?: string;
+  detail?: string;
+  instance?: string;
+  errors?: Array<ProblemDetailsParam>;
+};

package/lib/utils/alwaysArray.ts

@@ -0,0 +1,10 @@
+export function alwaysArray<T>(value: T | Array<T>): Array<T> {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (typeof value !== 'undefined' && value !== null) {
+    return [value];
+  }
+
+  return [];
+}

package/lib/utils/contextBuilder.ts

@@ -0,0 +1,111 @@
+import type { JSONLDContext, ContextVersion, TypeDef } from "../jsonld.js";
+import { isNil } from "./isNil.js";
+import { isPopulatedObject } from "./isPopulatedObject.js";
+
+export function contextBuilder({
+  vocab,
+  version = 1.1,
+  protect = false,
+  idTerm,
+  aliases,
+  typeDefs: argsTypeDefs,
+}: {
+  idTerm?: string;
+  vocab?: string;
+  version?: ContextVersion;
+  protect?: boolean;
+  aliases?: Record<string, string>;
+  typeDefs?: Record<string, TypeDef> | Array<TypeDef>;
+}): JSONLDContext {
+  let typeDefs: null | Array<TypeDef> = null;
+
+  if (Array.isArray(argsTypeDefs)) {
+    typeDefs = argsTypeDefs;
+  } else if (!isNil(argsTypeDefs)) {
+    typeDefs = Object.values(argsTypeDefs);
+  }
+
+  const inverseAliases: Record<string, string> = {};
+  const shadowedAliases: string[] = [];
+  const context: JSONLDContext = {};
+
+  if (version === 1.1) {
+    context['@version'] = version;
+  }
+
+  if (vocab != null) {
+    context['@vocab'] = vocab;
+  }
+
+  if (protect) {
+    context['@protected'] = true;
+  }
+
+  if (idTerm != null) {
+    context[idTerm] = '@id';
+  }
+
+  if (Array.isArray(typeDefs)) {
+    for (const typeDef of typeDefs) {
+      if (typeDef.term.startsWith('@')) {
+        throw new Error(`Terms cannot start with @. Recieved ${typeDef.term}`);
+      }
+
+      if (
+        typeof aliases !== 'undefined' && Object.hasOwn(aliases, typeDef.term)
+      ) {
+        shadowedAliases.push(typeDef.term);
+      }
+    }
+  }
+
+  if (typeof aliases !== 'undefined') {
+    for (const [alias, iri] of Object.entries(aliases)) {
+      if (iri === vocab) {
+        continue;
+      }
+
+      if (!shadowedAliases.includes(alias)) {
+        context[alias] = iri;
+        inverseAliases[iri] = alias;
+      }
+    }
+  }
+
+  if (Array.isArray(typeDefs)) {
+    for (const typeDef of typeDefs) {
+      if (idTerm === typeDef.term) {
+        continue;
+      }
+
+      let type: string = typeDef.type;
+      const matchesVocab = typeDef.type.startsWith(vocab);
+
+      if (vocab != null && matchesVocab) {
+        type = typeDef.type.replace(vocab, '');
+      } else if (typeof aliases !== 'undefined') {
+        for (const [alias, value] of Object.entries(aliases)) {
+          if (typeDef.type.startsWith(value)) {
+            type = typeDef.type.replace(value, `${alias}:`);
+          }
+        }
+      }
+
+      if (!matchesVocab && isPopulatedObject(typeDef.contextDefinition)) {
+        context[typeDef.term] = {
+          '@id': type,
+          ...typeDef.contextDefinition,
+        };
+      } else if (isPopulatedObject(typeDef.contextDefinition)) {
+        context[typeDef.term] = {
+          '@id': type,
+          ...typeDef.contextDefinition,
+        };
+      } else if (!matchesVocab) {
+        context[typeDef.term] = type;
+      }
+    }
+  }
+
+  return context;
+}

package/lib/utils/getActionContext.ts

@@ -0,0 +1,76 @@
+import type { JSONLDContext, TypeDef } from "../jsonld.js";
+import { makeTypeDef, makeTypeDefs } from "../makeTypeDefs.js";
+import { contextBuilder } from "./contextBuilder.js";
+import type { ActionSpec, PropertySpec } from '../actions/spec.js';
+
+const defaultTypeDefs = makeTypeDefs([
+  makeTypeDef({ schema: 'https://schema.org/', term: 'Entrypoint' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'target' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'httpMethod' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'urlTemplate' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'PropertyValueSpecification' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'maxValue' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'minValue' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'readonlyValue' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'stepValue' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'valueName' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'valueRequired' }),
+  makeTypeDef({ schema: 'https://schema.org/', term: 'multipleValues' }),
+]);
+
+export function getActionContext({
+  spec,
+  vocab,
+  aliases,
+}: {
+  vocab?: string;
+  aliases?: Record<string, string>;
+  // deno-lint-ignore no-explicit-any
+  spec: ActionSpec
+}): JSONLDContext {
+  const typeDefs: TypeDef[] = Object.values(defaultTypeDefs);
+
+  function searchAndAssignContextValues(
+    term: string,
+    propertySpec: PropertySpec,
+  ) {
+    if (propertySpec.typeDef != null) {
+      typeDefs.push(propertySpec.typeDef);
+      typeDefs.push(
+        makeTypeDef({
+          term: `${term}-input`,
+          type: `${propertySpec.typeDef.type}-input`,
+        }),
+      );
+    } else if (propertySpec.type === 'string') {
+      typeDefs.push(makeTypeDef({ term, type: propertySpec.type }));
+      typeDefs.push(
+        makeTypeDef({
+          term: `${term}-input`,
+          type: `${propertySpec.type}-input`,
+        }),
+      );
+    }
+
+    if (propertySpec.properties != null) {
+      for (
+        const [term, childPropertySpec] of Object.entries(
+          propertySpec.properties,
+        )
+      ) {
+        searchAndAssignContextValues(term, childPropertySpec);
+      }
+    }
+  }
+
+  for (const [term, propertySpec] of Object.entries(spec)) {
+    searchAndAssignContextValues(term, propertySpec);
+  }
+
+
+  return contextBuilder({
+    vocab,
+    aliases,
+    typeDefs,
+  });
+}

package/lib/utils/getInternalName.ts

@@ -0,0 +1,15 @@
+import { isPopulatedString } from "./isPopulatedString.js";
+
+export function getInternalName({
+  paramName,
+  specValue,
+}: {
+  paramName: string;
+  specValue: { internalTerm?: string };
+}): string {
+  if (isPopulatedString(specValue.internalTerm)) {
+    return specValue.internalTerm;
+  }
+
+  return paramName;
+}

package/lib/utils/getParamLocation.ts

@@ -0,0 +1,14 @@
+
+
+export type ParamLocation =
+  | 'path'
+  | 'search'
+;
+
+export function getParamLocation(valueName: string, urlPattern: URLPattern): ParamLocation {
+  if (urlPattern.pathname.includes(`:${valueName}`)) {
+    return 'path';
+  }
+
+  return 'search';
+}