@deterministic-code/datasources 0.0.0-stage → 0.1.0

package/src/DatasourceFactory.ts

@@ -0,0 +1,86 @@
+import type { IDatasource } from "./IDatasource.ts";
+import type { IDatasourceFactory } from "./IDatasourceFactory.ts";
+import type { IDriver } from "./IDriver.ts";
+import type { DatasourceOptions } from "./DatasourceOptions.ts";
+import { Datasource } from "./Datasource.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import { DatasourceUrlParser } from "./DatasourceUrlParser.ts";
+import { DriverLoader } from "./DriverLoader.ts";
+import { DotEnv } from "./dotEnv.ts";
+import { ProviderCatalog } from "./ProviderCatalog.ts";
+import { ProviderNotInstalledError } from "./ProviderNotInstalledError.ts";
+
+const factories = new Map<string, IDriver>();
+
+const get = (options: DatasourceOptions | undefined, key: string): string | undefined => {
+  const value = options?.[key];
+  return value && value.trim() ? value.trim() : undefined;
+};
+
+const nonEmpty = (value: string | undefined): string | undefined =>
+  value?.trim() ? value.trim() : undefined;
+
+const merge = (file: DatasourceOptions, env: Record<string, string | undefined>): DatasourceOptions => {
+  const options: DatasourceOptions = { ...file };
+  for (const key of ["INSTALLED_PROVIDERS", "DATASOURCE_URL", "PROVIDER"] as const) {
+    const value = nonEmpty(env[key]);
+    if (value) options[key] = value;
+  }
+  return options;
+};
+
+const split = (value: string | undefined): string[] =>
+  (value ?? "")
+    .split(",")
+    .map((name) => name.trim())
+    .filter((name) => name.length > 0);
+
+function* installed(options: DatasourceOptions): Generator<string> {
+  const names = new Set<string>();
+  for (const name of split(get(options, "INSTALLED_PROVIDERS"))) {
+    if (names.has(name)) continue;
+    names.add(name);
+    yield name;
+  }
+  const url = get(options, "DATASOURCE_URL");
+  if (!url) return;
+  const provider = DatasourceUrlParser.parse(url)?.provider;
+  if (!provider) throw new DatasourceError("DATASOURCE_URL has no provider");
+  if (!names.has(provider)) yield provider;
+}
+
+const registerInstalled = (options: DatasourceOptions): void => {
+  for (const name of installed(options)) {
+    const catalog = ProviderCatalog.default[name];
+    if (!catalog) throw new ProviderNotInstalledError(name);
+    DatasourceFactory.register(name, DriverLoader.load(catalog));
+  }
+};
+
+const resolve = (options?: DatasourceOptions): IDatasource => {
+  const listed = options ?? merge(DotEnv.load(), process.env);
+  if (options === undefined) registerInstalled(listed);
+  const name = get(listed, "PROVIDER")
+    ?? (() => { throw new DatasourceError("Datasource defaults are not specified"); })();
+  const driver = factories.get(name);
+  if (!driver) throw new ProviderNotInstalledError(name);
+  return new Datasource(name, driver, listed);
+};
+
+export class DatasourceFactory implements IDatasourceFactory {
+  static defaults = (options: DatasourceOptions): void => registerInstalled(options);
+
+  static register = (provider: string, driver: IDriver): void => {
+    factories.set(provider, driver);
+  };
+
+  static create = (options?: DatasourceOptions): IDatasource => resolve(options);
+
+  create = (options?: DatasourceOptions): IDatasource => resolve(options);
+
+  static reset = (): void => {
+    factories.clear();
+  };
+
+  static registered = (): string[] => [...factories.keys()].sort();
+}

package/src/DatasourceOptions.ts

@@ -0,0 +1 @@
+export type DatasourceOptions = Record<string, string>;

package/src/DatasourceUrl.ts

@@ -0,0 +1,37 @@
+export class DatasourceUrl {
+  readonly provider: string;
+  readonly username: string | undefined;
+  readonly password: string | undefined;
+  readonly host: string | undefined;
+  readonly port: number | undefined;
+  readonly path: string;
+  readonly schema: string | undefined;
+  readonly options: Readonly<Record<string, string>>;
+
+  constructor(
+    provider: string,
+    username: string | undefined,
+    password: string | undefined,
+    host: string | undefined,
+    port: number | undefined,
+    path: string,
+    schema: string | undefined,
+    options: Readonly<Record<string, string>>,
+  ) {
+    this.provider = provider;
+    this.username = username;
+    this.password = password;
+    this.host = host;
+    this.port = port;
+    this.path = path;
+    this.schema = schema;
+    this.options = options;
+  }
+
+  get datasource(): string | undefined {
+    if (this.path === "") return undefined;
+    if (!this.path.startsWith("/")) return this.path;
+    const rest = this.path.slice(1);
+    return rest === "" ? undefined : rest;
+  }
+}

package/src/DatasourceUrlParser.ts

@@ -0,0 +1,188 @@
+import { DatasourceUrl } from "./DatasourceUrl.ts";
+
+const empty: Readonly<Record<string, string>> = {};
+
+const schemeStart = (c: string): boolean =>
+  (c >= "A" && c <= "Z") || (c >= "a" && c <= "z");
+
+const schemeChar = (c: string): boolean =>
+  schemeStart(c) || (c >= "0" && c <= "9") || c === "+" || c === "." || c === "-";
+
+const schemeColon = (url: string): number | undefined => {
+  if (!schemeStart(url.charAt(0))) return undefined;
+  let i = 1;
+  while (i < url.length && schemeChar(url[i])) i++;
+  return i < url.length && url[i] === ":" ? i : undefined;
+};
+
+const hex = (text: string): number | undefined =>
+  /^[0-9a-fA-F]{2}$/.test(text) ? Number.parseInt(text, 16) : undefined;
+
+const decode = (text: string): string | undefined => {
+  const bytes: number[] = [];
+  let decoded = "";
+  const flush = (): void => {
+    if (bytes.length === 0) return;
+    decoded += new TextDecoder().decode(new Uint8Array(bytes));
+    bytes.length = 0;
+  };
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c !== "%") {
+      const code = text.charCodeAt(i);
+      if (code <= 127) bytes.push(code);
+      else {
+        flush();
+        decoded += c;
+      }
+      continue;
+    }
+    const byte = i + 2 < text.length ? hex(text.slice(i + 1, i + 3)) : undefined;
+    if (byte === undefined) return undefined;
+    bytes.push(byte);
+    i += 2;
+  }
+  flush();
+  return decoded;
+};
+
+const portOf = (text: string): number | undefined =>
+  /^[0-9]+$/.test(text) ? Number.parseInt(text, 10) : undefined;
+
+type Authority = {
+  username: string | undefined;
+  password: string | undefined;
+  host: string | undefined;
+  port: number | undefined;
+  file: string | undefined;
+};
+
+const userOf = (user: string): { username: string | undefined; password: string | undefined } | undefined => {
+  const colon = user.indexOf(":");
+  const username = decode(colon < 0 ? user : user.slice(0, colon));
+  if (username === undefined) return undefined;
+  if (colon < 0) return { username: username === "" ? undefined : username, password: undefined };
+  const password = decode(user.slice(colon + 1));
+  if (password === undefined) return undefined;
+  return { username: username === "" ? undefined : username, password };
+};
+
+const hostLiteral = (hostport: string): { host: string | undefined; port: number | undefined } | undefined => {
+  const end = hostport.indexOf("]");
+  if (end < 1) return undefined;
+  const host = decode(hostport.slice(1, end));
+  if (host === undefined) return undefined;
+  if (end + 1 === hostport.length) return { host, port: undefined };
+  if (hostport[end + 1] !== ":") return undefined;
+  const port = portOf(hostport.slice(end + 2));
+  return port === undefined ? undefined : { host, port };
+};
+
+const authorityOf = (authority: string, hasPath: boolean): Authority | undefined => {
+  if (authority.length === 0)
+    return { username: undefined, password: undefined, host: undefined, port: undefined, file: undefined };
+  const at = authority.lastIndexOf("@");
+  let hostport = authority;
+  let username: string | undefined;
+  let password: string | undefined;
+  if (at >= 0) {
+    const user = userOf(authority.slice(0, at));
+    if (!user) return undefined;
+    username = user.username;
+    password = user.password;
+    hostport = authority.slice(at + 1);
+  }
+  const base = { username, password, file: undefined };
+  if (hostport.length === 0) return { ...base, host: undefined, port: undefined };
+  if (hostport[0] === "[") {
+    const literal = hostLiteral(hostport);
+    return literal ? { ...base, host: literal.host, port: literal.port } : undefined;
+  }
+  const colon = hostport.lastIndexOf(":");
+  if (colon >= 0) {
+    const port = portOf(hostport.slice(colon + 1));
+    if (port !== undefined) {
+      const name = hostport.slice(0, colon);
+      if (name.length === 0) return { ...base, host: undefined, port };
+      const host = decode(name);
+      return host === undefined ? undefined : { ...base, host, port };
+    }
+  }
+  if (!hasPath && at < 0 && hostport[0] !== ":") {
+    const file = decode(hostport);
+    return file === undefined ? undefined : { ...base, host: undefined, port: undefined, file };
+  }
+  const host = decode(hostport);
+  return host === undefined ? undefined : { ...base, host, port: undefined };
+};
+
+const queryOf = (
+  query: string,
+): { schema: string | undefined; options: Readonly<Record<string, string>> } | undefined => {
+  if (query.length === 0) return { schema: undefined, options: empty };
+  const options: Record<string, string> = {};
+  let schema: string | undefined;
+  for (const part of query.split("&")) {
+    if (part.length === 0) continue;
+    const eq = part.indexOf("=");
+    const key = decode(eq < 0 ? part : part.slice(0, eq));
+    const value = decode(eq < 0 ? "" : part.slice(eq + 1));
+    if (key === undefined || value === undefined) return undefined;
+    if (key === "schema") schema = value;
+    else options[key] = value;
+  }
+  return { schema, options };
+};
+
+const partsOf = (
+  rest: string,
+):
+  | {
+      username: string | undefined;
+      password: string | undefined;
+      host: string | undefined;
+      port: number | undefined;
+      path: string;
+    }
+  | undefined => {
+  if (!rest.startsWith("//"))
+    return { username: undefined, password: undefined, host: undefined, port: undefined, path: rest };
+  const body = rest.slice(2);
+  const slash = body.indexOf("/");
+  const authority = authorityOf(slash >= 0 ? body.slice(0, slash) : body, slash >= 0);
+  if (!authority) return undefined;
+  return {
+    username: authority.username,
+    password: authority.password,
+    host: authority.host,
+    port: authority.port,
+    path: authority.file ?? (slash >= 0 ? body.slice(slash) : ""),
+  };
+};
+
+export class DatasourceUrlParser {
+  static parse(url: string | undefined): DatasourceUrl | undefined {
+    if (url === undefined || url.trim() === "") return undefined;
+    const colon = schemeColon(url);
+    if (colon === undefined) return undefined;
+    let rest = url.slice(colon + 1);
+    const hash = rest.indexOf("#");
+    if (hash >= 0) rest = rest.slice(0, hash);
+    const queryAt = rest.indexOf("?");
+    const query = queryAt >= 0 ? rest.slice(queryAt + 1) : "";
+    if (queryAt >= 0) rest = rest.slice(0, queryAt);
+    const parts = partsOf(rest);
+    const parsed = queryOf(query);
+    if (!parts || !parsed) return undefined;
+    return new DatasourceUrl(
+      url.slice(0, colon).toLowerCase(),
+      parts.username,
+      parts.password,
+      parts.host,
+      parts.port,
+      parts.path,
+      parsed.schema,
+      parsed.options,
+    );
+  }
+}

package/src/DefaultCreateEnrichmentStrategy.ts

@@ -0,0 +1,21 @@
+import { CreateEnrichmentStrategy } from "./CreateEnrichmentStrategy.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import type { Enrichment } from "./Enrichment.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+
+export class DefaultCreateEnrichmentStrategy<T> extends CreateEnrichmentStrategy<T> {
+  async createChildren<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void> {
+    for (const related of this.payloadOf<TChild, T>(parent, enrichment.destinationProperty, enrichment)) {
+      this.stampCell(related, enrichment.relatedKey, this.getCell(parent, enrichment.sourceProperty));
+      await writer.create(related);
+    }
+  }
+
+  async createLinked<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void> {
+    const association = enrichment.association;
+    if (!association) throw new DatasourceError("Missing association");
+    const parentKey = this.requiredKey(parent, enrichment);
+    for (const id of this.relatedIds(parent, enrichment))
+      await writer.create({ [association.parent]: parentKey, [association.related]: id } as TChild);
+  }
+}

package/src/DefaultReadonlyEnrichmentStrategy.ts

@@ -0,0 +1,164 @@
+import type { Scalar } from "./builders/Scalar.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import type { Enrichment } from "./Enrichment.ts";
+import { EnrichmentPropertyType } from "./EnrichmentPropertyType.ts";
+import type { IReadonlyEnrichmentStrategy } from "./IReadonlyEnrichmentStrategy.ts";
+import type { IReadonlyRepository } from "./IReadonlyRepository.ts";
+import type { Row } from "./Row.ts";
+import { Operator, Where } from "./statements/index.ts";
+
+type Props = Record<string, Scalar | object>;
+
+export class DefaultReadonlyEnrichmentStrategy<T extends object>
+  implements IReadonlyEnrichmentStrategy<T>
+{
+  apply<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    const type = enrichment.type ?? EnrichmentPropertyType.Object;
+    const run = {
+      [EnrichmentPropertyType.List]: () => this.applyList(via, enrichment, parents, sources),
+      [EnrichmentPropertyType.Object]: () => this.applyObject(via, enrichment, parents, sources),
+      [EnrichmentPropertyType.Dictionary]: () => this.applyDictionary(via, enrichment, parents, sources),
+    }[type];
+    return run ? run() : Promise.reject(new DatasourceError(`Unsupported enrichment type "${type}"`));
+  }
+
+  async applyLinked<TRelated extends object, TLink extends object>(
+    via: IReadonlyRepository<TRelated>,
+    link: IReadonlyRepository<TLink>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    const association = enrichment.association ?? (() => {
+      throw new DatasourceError("Missing association");
+    })();
+    for (const [index, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, enrichment.sourceProperty, sources, index);
+      if (key === undefined || key === null) continue;
+      const related: TRelated[] = [];
+      for await (const row of link.read(
+        new Where(new Operator.Equals(association.parent, this.scalar(key))),
+      )) {
+        const id = this.props(row)[association.related];
+        if (id === undefined || id === null || typeof id === "object") continue;
+        const entity = await via.readSingle(new Where(new Operator.Equals(enrichment.relatedKey, id)));
+        if (entity) related.push(entity);
+      }
+      Object.assign(parent, { [enrichment.destinationProperty]: related });
+    }
+  }
+
+  protected async applyObject<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    const cache = new Map<string, TRelated | undefined>();
+    for (const [index, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, enrichment.sourceProperty, sources, index);
+      if (key === undefined || key === null) continue;
+      const cacheKey = this.keyOf(key);
+      if (!cache.has(cacheKey))
+        cache.set(
+          cacheKey,
+          await via.readSingle(new Where(new Operator.Equals(enrichment.relatedKey, this.scalar(key)))),
+        );
+      const related = cache.get(cacheKey);
+      if (!related) continue;
+      Object.assign(parent, {
+        [enrichment.destinationProperty]: enrichment.relatedProperty ? this.props(related)[enrichment.relatedProperty] : related,
+      });
+    }
+  }
+
+  protected async applyList<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    for (const [index, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, enrichment.sourceProperty, sources, index);
+      if (key === undefined || key === null) continue;
+      const related: TRelated[] = [];
+      for await (const item of via.read(
+        new Where(new Operator.Equals(enrichment.relatedKey, this.scalar(key))),
+      ))
+        related.push(item);
+      Object.assign(parent, { [enrichment.destinationProperty]: related });
+    }
+  }
+
+  protected async applyDictionary<TRelated extends object>(
+    via: IReadonlyRepository<TRelated>,
+    enrichment: Enrichment,
+    parents: T[],
+    sources?: (Row | undefined)[],
+  ): Promise<void> {
+    const mapKey = mapKeyName(enrichment.relatedKey);
+    for (const [index, parent] of parents.entries()) {
+      const key = this.sourceKey(parent, enrichment.sourceProperty, sources, index);
+      if (key === undefined || key === null) continue;
+      const map: Record<string, Scalar | object> = {};
+      for await (const item of via.read(
+        new Where(new Operator.Equals(enrichment.relatedKey, this.scalar(key))),
+      )) {
+        const row = this.props(item);
+        const entry = row[mapKey];
+        if (entry === undefined || entry === null || typeof entry === "object") continue;
+        map[String(entry)] = enrichment.relatedProperty
+          ? (row[enrichment.relatedProperty] ?? null)
+          : Object.fromEntries(
+              Object.entries(row).filter(
+                ([name]) => name !== mapKey && name !== enrichment.relatedKey && name !== "Id" && name !== "id",
+              ),
+            );
+      }
+      Object.assign(parent, { [enrichment.destinationProperty]: map });
+    }
+  }
+
+  protected sourceKey(
+    parent: T,
+    name: string,
+    sources: (Row | undefined)[] | undefined,
+    index: number,
+  ): Scalar | object | undefined {
+    const cell = sources?.[index]?.[name];
+    const raw = cell !== undefined && cell !== null ? cell : this.props(parent)[name];
+    return this.lookupKey(raw);
+  }
+
+  protected props = <TItem>(item: TItem): Props => item as never as Props;
+
+  protected keyOf = (key: Scalar | object): string => String(this.lookupKey(key));
+
+  protected lookupKey = (value: Scalar | object | undefined): Scalar | object | undefined => {
+    if (value === undefined || value === null || typeof value !== "object") return value;
+    const id = this.props(value).Id ?? this.props(value).id;
+    return id !== undefined && id !== null && typeof id !== "object" ? id : value;
+  };
+
+  protected scalar = (value: Scalar | object): Scalar => {
+    const key = this.lookupKey(value);
+    return key === null ||
+      typeof key === "string" ||
+      typeof key === "number" ||
+      typeof key === "boolean" ||
+      typeof key === "bigint"
+      ? key
+      : (() => {
+          throw new DatasourceError("Enrichment key must be a scalar");
+        })();
+  };
+}
+
+const mapKeyName = (relatedKey: string): string =>
+  relatedKey.includes("_") || relatedKey[0] !== relatedKey[0]?.toUpperCase() ? "key" : "Key";
+

package/src/DefaultUpdateEnrichmentStrategy.ts

@@ -0,0 +1,40 @@
+import { DatasourceError } from "./DatasourceError.ts";
+import { DeleteEnrichmentStrategy } from "./DeleteEnrichmentStrategy.ts";
+import type { Enrichment } from "./Enrichment.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import { UpdateEnrichmentStrategy } from "./UpdateEnrichmentStrategy.ts";
+
+export class DefaultUpdateEnrichmentStrategy<T> extends UpdateEnrichmentStrategy<T> {
+  async updateChildren<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void> {
+    const existing = await DeleteEnrichmentStrategy.load(writer, enrichment, parent);
+    const rows = this.payloadOf<TChild, T>(parent, enrichment.destinationProperty, enrichment);
+    for (const related of rows) this.stampCell(related, enrichment.relatedKey, this.getCell(parent, enrichment.sourceProperty));
+    const keys = this.namesOf(writer, rows[0] ?? existing[0] ?? {} as TChild);
+    const keep = new Set(rows.filter((row) => this.hasKey(row, keys)).map((row) => this.keyOf(row, keys)));
+    for (const row of existing.filter((row) => !keep.has(this.keyOf(row, keys))))
+      await writer.delete(row, DeleteEnrichmentStrategy.childrenWhere(writer, enrichment, parent));
+    for (const related of rows)
+      this.hasKey(related, keys) && existing.some((row) => this.keyOf(row, keys) === this.keyOf(related, keys))
+        ? await writer.update(related)
+        : await writer.create(related);
+  }
+
+  async updateLinked<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void> {
+    const association = enrichment.association;
+    if (!association) throw new DatasourceError("Missing association");
+    const parentKey = this.requiredKey(parent, enrichment);
+    const existing = await DeleteEnrichmentStrategy.loadLinks(writer, association.parent, parentKey);
+    const wanted = this.relatedIds(parent, enrichment);
+    const keep = new Set(wanted.map((id) => String(id)));
+    for (const row of existing) {
+      const id = this.getCell(row, association.related);
+      if (this.presentCell(id) && keep.has(String(id))) continue;
+      if (!this.presentCell(id)) continue;
+      await writer.delete(row, this.linkWhere(association, parentKey, id));
+    }
+    for (const id of wanted) {
+      if (existing.some((row) => String(this.getCell(row, association.related) ?? "") === String(id))) continue;
+      await writer.create({ [association.parent]: parentKey, [association.related]: id } as TChild);
+    }
+  }
+}