@deterministic-code/datasources 0.0.0-stage → 0.1.0

package/src/UpdateEnrichmentStrategy.ts

@@ -0,0 +1,97 @@
+import type { Enrichment } from "./Enrichment.ts";
+import type { ICRUDRepository } from "./ICRUDRepository.ts";
+import type { Scalar } from "./builders/Scalar.ts";
+import { defaultId } from "./createCRUDRepositoryOptions.ts";
+import { DatasourceError } from "./DatasourceError.ts";
+import { Operator, Where } from "./statements/index.ts";
+
+type Props = Record<string, Scalar | object>;
+
+export abstract class UpdateEnrichmentStrategy<T> {
+  abstract updateChildren<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void>;
+
+  abstract updateLinked<TChild extends object>(writer: ICRUDRepository<TChild>, enrichment: Enrichment, parent: T): Promise<void>;
+
+  protected getCell = <TItem>(item: TItem, name: string): Scalar | object | undefined =>
+    (item as never as Props)[name];
+
+  protected presentCell = (value: Scalar | object | undefined): value is Scalar =>
+    value !== undefined && value !== null && typeof value !== "object" && value !== 0 && value !== 0n && value !== "";
+
+  protected payloadOf = <TChild extends object, TParent>(
+    parent: TParent,
+    into: string,
+    enrichment?: Enrichment,
+  ): TChild[] => mapPayload(this.getCell(parent, into), enrichment) as TChild[];
+
+  protected stampCell = <TItem extends object>(related: TItem, by: string, key: Scalar | object | undefined): void => {
+    if (key === undefined || key === null || typeof key === "object") return;
+    const current = this.getCell(related, by);
+    if (current !== null && typeof current === "object" && !Array.isArray(current)) {
+      const target = current as Props;
+      const id = "Id" in target ? "Id" : "id";
+      target[id] = key;
+      return;
+    }
+    Object.assign(related, { [by]: key });
+  };
+
+  protected hasKey = <TItem extends object>(item: TItem, keys: readonly string[]): boolean =>
+    keys.length > 0 && keys.every((name) => this.presentCell(this.getCell(item, name)));
+
+  protected keyOf = <TItem extends object>(item: TItem, keys: readonly string[]): string =>
+    keys.map((name) => String(this.getCell(item, name) ?? "")).join("\u001f");
+
+  protected namesOf = <TChild extends object>(writer: ICRUDRepository<TChild>, item: TChild): readonly string[] =>
+    writer.ids.length > 0 ? writer.ids : defaultId(Object.keys(item));
+
+  protected linkWhere = (
+    association: NonNullable<Enrichment["association"]>,
+    parentKey: Scalar,
+    relatedKey: Scalar,
+  ): Where =>
+    new Where(
+      new Operator.And(
+        new Operator.Equals(association.parent, parentKey),
+        new Operator.Equals(association.related, relatedKey),
+      ),
+    );
+
+  protected relatedIds = <TParent>(parent: TParent, enrichment: Enrichment): Scalar[] => {
+    const ids: Scalar[] = [];
+    const seen = new Set<string>();
+    for (const related of this.payloadOf<object, TParent>(parent, enrichment.destinationProperty)) {
+      const id = this.getCell(related, enrichment.relatedKey);
+      if (!this.presentCell(id)) throw new DatasourceError(`${enrichment.destinationProperty} requires "${enrichment.relatedKey}"`);
+      const key = String(id);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      ids.push(id);
+    }
+    return ids;
+  };
+
+  protected requiredKey = <TParent>(parent: TParent, enrichment: Enrichment): Scalar => {
+    const key = this.getCell(parent, enrichment.sourceProperty);
+    if (!this.presentCell(key)) throw new DatasourceError(`${enrichment.destinationProperty} requires "${enrichment.sourceProperty}"`);
+    return key;
+  };
+}
+
+const mapPayload = (value: Scalar | object | undefined, enrichment?: Enrichment): object[] => {
+  if (value === undefined || value === null || typeof value === "string") return [];
+  if (Array.isArray(value)) return value.filter((item) => item !== null && typeof item === "object");
+  if (enrichment?.type !== "dictionary" || typeof value !== "object") return [];
+  const keyName = mapKeyName(enrichment.relatedKey);
+  const valueName = enrichment.relatedProperty ?? (keyName === "Key" ? "Value" : "value");
+  return Object.entries(value as Record<string, Scalar | object>)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, cell]) =>
+      cell !== null && typeof cell === "object" && !Array.isArray(cell)
+        ? { [keyName]: key, ...(cell as object) }
+        : { [keyName]: key, [valueName]: cell },
+    );
+};
+
+const mapKeyName = (relatedKey: string): string =>
+  relatedKey.includes("_") || relatedKey[0] !== relatedKey[0]?.toUpperCase() ? "key" : "Key";

package/src/WriteMode.ts

@@ -0,0 +1 @@
+export type WriteMode = "create" | "update" | "delete";

package/src/builders/Field.ts

@@ -0,0 +1,6 @@
+import type { Scalar } from "./Scalar.ts";
+
+export interface Field {
+  name: string;
+  value: Scalar;
+}

package/src/builders/Scalar.ts

@@ -0,0 +1 @@
+export type Scalar = string | number | boolean | bigint | null;

package/src/builders/index.ts

@@ -0,0 +1,2 @@
+export type { Field } from "./Field.ts";
+export type { Scalar } from "./Scalar.ts";

package/src/collectAsync.ts

@@ -0,0 +1,7 @@
+export async function collectAsync<T>(items: AsyncIterable<T>): Promise<T[]> {
+  const collected: T[] = [];
+  for await (const item of items) {
+    collected.push(item);
+  }
+  return collected;
+}

package/src/converters/Cell.ts

@@ -0,0 +1,10 @@
+export type Cell =
+  | string
+  | number
+  | boolean
+  | bigint
+  | Date
+  | Uint8Array
+  | null;
+
+export type Cells = Record<string, Cell>;

package/src/converters/ChangeCasingConverter.ts

@@ -0,0 +1,59 @@
+export type Casing =
+  | "camelCase"
+  | "capitalCase"
+  | "constantCase"
+  | "dotCase"
+  | "kebabCase"
+  | "noCase"
+  | "pascalCase"
+  | "pascalSnakeCase"
+  | "pathCase"
+  | "sentenceCase"
+  | "snakeCase"
+  | "trainCase";
+
+const cap = (word: string) => word[0].toUpperCase() + word.slice(1);
+const sep = (c: string) => c === "_" || c === "." || c === "-" || c === "/" || /\s/.test(c);
+const upper = (c: string) => c !== c.toLowerCase();
+const lower = (c: string) => c !== c.toUpperCase();
+const letter = (c: string) => upper(c) || lower(c);
+const digit = (c: string) => c >= "0" && c <= "9";
+
+const words = (text: string): string[] => {
+  const parts: string[] = [];
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const split =
+      sep(text[i]) ||
+      (i > 0 && lower(text[i - 1]) && upper(text[i])) ||
+      (i > 0 && i + 1 < text.length && upper(text[i - 1]) && upper(text[i]) && lower(text[i + 1])) ||
+      (i > 0 && letter(text[i - 1]) !== letter(text[i]) && (letter(text[i - 1]) || digit(text[i - 1])) && (letter(text[i]) || digit(text[i])));
+    if (!split) continue;
+    if (i > start) parts.push(text.slice(start, i));
+    start = sep(text[i]) ? i + 1 : i;
+  }
+  if (start < text.length) parts.push(text.slice(start));
+  return parts.map((word) => word.toLowerCase()).filter((word) => word.length > 0);
+};
+
+const join = (parts: string[], casing: Casing): string =>
+  ({
+    camelCase: () => parts.map((word, i) => (i === 0 ? word : cap(word))).join(""),
+    capitalCase: () => parts.map(cap).join(" "),
+    constantCase: () => parts.map((word) => word.toUpperCase()).join("_"),
+    dotCase: () => parts.join("."),
+    kebabCase: () => parts.join("-"),
+    noCase: () => parts.join(" "),
+    pascalCase: () => parts.map(cap).join(""),
+    pascalSnakeCase: () => parts.map(cap).join("_"),
+    pathCase: () => parts.join("/"),
+    sentenceCase: () => parts.map((word, i) => (i === 0 ? cap(word) : word)).join(" "),
+    snakeCase: () => parts.join("_"),
+    trainCase: () => parts.map(cap).join("-"),
+  }[casing]());
+
+export class ChangeCasingConverter {
+  constructor(private readonly casing: Casing) {}
+  convert = (from: string) => join(words(from), this.casing);
+  reverseConvert = (to: string) => to;
+}

package/src/converters/Constructable.ts

@@ -0,0 +1 @@
+export type Constructable<T> = new () => T;

package/src/converters/MetaDataRowTypeConverter.ts

@@ -0,0 +1,80 @@
+import type { Cell, Cells } from "./Cell.ts";
+import { TypeConverter } from "./TypeConverter.ts";
+import type { Constructable } from "./Constructable.ts";
+import type { IMapper } from "../mappers/IMapper.ts";
+import { IdentityMapper } from "../mappers/IdentityMapper.ts";
+
+const scalarId = (value: Cell | object | undefined): Cell | undefined => {
+  if (value === undefined || value === null || typeof value !== "object" || value instanceof Date || value instanceof Uint8Array)
+    return value === undefined ? undefined : (value as Cell);
+  const record = value as Record<string, Cell | undefined>;
+  return record.Id !== undefined ? record.Id : record.id;
+};
+
+export class MetaDataRowTypeConverter<T = Cells> extends TypeConverter<T, Cells> {
+  fields: Record<string, TypeConverter<Cell, Cell>>;
+  references = new Set<string>();
+  referenceColumns: IMapper<string, string> = new IdentityMapper<string>();
+  shouldCoerceId = false;
+
+  constructor(fields: Record<string, TypeConverter<Cell, Cell>> = {}) {
+    super();
+    this.fields = { ...fields };
+  }
+
+  convert = (row: Cells, type?: Constructable<T>): T => {
+    const blank = type ? new type() : {};
+    const cells = Object.fromEntries(
+      Object.entries(row).filter(([key, value]) => {
+        if (this.references.has(key)) return false;
+        const current = (blank as Cells)[key];
+        return !(typeof current === "string" && typeof value !== "string" && value !== null);
+      }),
+    );
+    const dest = Object.assign(blank, cells) as T;
+    const record = dest as Record<string, Cell | object>;
+    for (const [key, value] of Object.entries(row)) {
+      if (this.references.has(key)) {
+        const current = record[key];
+        const target = current !== null && typeof current === "object" && !Array.isArray(current)
+          ? current as Record<string, Cell>
+          : {};
+        const id = "Id" in target ? "Id" : "id";
+        target[id] = value;
+        record[key] = target;
+        continue;
+      }
+      const converter = this.fields[key];
+      if (converter) record[key] = converter.convert(value);
+    }
+    return dest;
+  };
+
+  reverseConvert = (row: T): Cells => {
+    const cells: Cells = {};
+    for (const [key, value] of Object.entries(row as Record<string, Cell | object>)) {
+      if (Array.isArray(value)) continue;
+      if (
+        value !== null &&
+        typeof value === "object" &&
+        !(value instanceof Date) &&
+        !(value instanceof Uint8Array) &&
+        !this.references.has(key)
+      )
+        continue;
+      if (this.references.has(key)) {
+        const id = scalarId(value);
+        if (id !== undefined && id !== null) cells[this.referenceColumns.map(key)] = this.converted(key, id);
+        continue;
+      }
+      const converter = this.fields[key];
+      cells[key] = converter ? converter.reverseConvert(value as Cell) : (value as Cell);
+    }
+    return cells;
+  };
+
+  private converted = (key: string, value: Cell): Cell => {
+    const converter = this.fields[key];
+    return converter ? converter.reverseConvert(value) : value;
+  };
+}

package/src/converters/PluralizerConverter.ts

@@ -0,0 +1,67 @@
+const uncountable = new Set(["sheep", "fish", "series", "species", "deer", "news"]);
+const irregular: Record<string, string> = {
+  person: "people",
+  child: "children",
+  man: "men",
+  woman: "women",
+  mouse: "mice",
+  goose: "geese",
+  tooth: "teeth",
+  foot: "feet",
+  ox: "oxen",
+};
+const irregularSingular = Object.fromEntries(
+  Object.entries(irregular).map(([singular, plural]) => [plural, singular]),
+);
+
+const vowel = (c: string) => "aeiou".includes(c);
+const consonant = (c: string) => /[a-z]/.test(c) && !vowel(c);
+const yies = (word: string) => word.length >= 4 && word.endsWith("ies") && consonant(word[word.length - 4]);
+const consonantY = (word: string) => word.length >= 2 && word.endsWith("y") && consonant(word[word.length - 2]);
+const sibilant = (word: string) =>
+  word.endsWith("ch") ||
+  word.endsWith("sh") ||
+  word.endsWith("x") ||
+  word.endsWith("z") ||
+  word.endsWith("ss") ||
+  (word.length >= 2 && word.endsWith("s") && !word.endsWith("es") && vowel(word[word.length - 2]));
+const sibilantEs = (word: string) => word.length > 2 && word.endsWith("es") && sibilant(word.slice(0, -2));
+
+const restore = (original: string, result: string) =>
+  original[0] === original[0].toUpperCase()
+    ? result[0].toUpperCase() + result.slice(1)
+    : result;
+
+const plural = (word: string) =>
+  uncountable.has(word) || word in irregularSingular
+    ? word
+    : irregular[word] ??
+      (yies(word) || sibilantEs(word)
+        ? word
+        : sibilant(word)
+          ? word + "es"
+          : consonantY(word)
+            ? word.slice(0, -1) + "ies"
+            : word.endsWith("s")
+              ? word
+              : word + "s");
+
+const singular = (word: string) =>
+  uncountable.has(word) || word in irregular
+    ? word
+    : (irregularSingular[word] ??
+      (yies(word)
+        ? word.slice(0, -3) + "y"
+        : sibilantEs(word)
+          ? word.slice(0, -2)
+          : word.endsWith("s") && !sibilant(word)
+            ? word.slice(0, -1)
+            : word));
+
+const apply = (word: string, transform: (word: string) => string) =>
+  word.length === 0 ? word : restore(word, transform(word.toLowerCase()));
+
+export class PluralizerConverter {
+  convert = (from: string) => apply(from, plural);
+  reverseConvert = (to: string) => apply(to, singular);
+}

package/src/converters/RegexConverter.ts

@@ -0,0 +1,14 @@
+export class RegexConverter {
+  readonly regex: RegExp;
+  readonly replacement: string;
+
+  constructor(pattern: string | RegExp, replacement: string) {
+    this.regex = typeof pattern === "string"
+      ? new RegExp(pattern, "g")
+      : new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`);
+    this.replacement = replacement;
+  }
+
+  convert = (from: string) => from.replace(this.regex, this.replacement);
+  reverseConvert = (to: string) => to;
+}

package/src/converters/ReplaceConverter.ts

@@ -0,0 +1,6 @@
+export class ReplaceConverter {
+  constructor(readonly search: string, readonly replacement: string) {}
+
+  convert = (from: string) => from.replaceAll(this.search, this.replacement);
+  reverseConvert = (to: string) => to.replaceAll(this.replacement, this.search);
+}

package/src/converters/RowTypeConverter.ts

@@ -0,0 +1,33 @@
+import type { Cell, Cells } from "./Cell.ts";
+import { TypeConverter } from "./TypeConverter.ts";
+
+export class RowTypeConverter extends TypeConverter<Cells, Cells> {
+  constructor(readonly fields: Record<string, TypeConverter<Cell, Cell>>) {
+    super();
+  }
+
+  static from(
+    converters: Record<string, TypeConverter<Cell, Cell>>,
+    columns: Record<string, string>,
+  ): RowTypeConverter {
+    const fields: Record<string, TypeConverter<Cell, Cell>> = {};
+    for (const [name, type] of Object.entries(columns)) {
+      const converter = converters[type];
+      if (converter) fields[name] = converter;
+    }
+    return new RowTypeConverter(fields);
+  }
+
+  convert = (from: Cells): Cells => this.apply(from, false);
+
+  reverseConvert = (to: Cells): Cells => this.apply(to, true);
+
+  private apply(row: Cells, reverse: boolean): Cells {
+    return Object.fromEntries(
+      Object.entries(row).map(([name, value]) => {
+        const converter = this.fields[name];
+        return [name, converter ? (reverse ? converter.reverseConvert(value) : converter.convert(value)) : value];
+      }),
+    );
+  }
+}

package/src/converters/ToLowerCaseConverter.ts

@@ -0,0 +1,4 @@
+export class ToLowerCaseConverter {
+  convert = (from: string) => from.toLowerCase();
+  reverseConvert = (to: string) => to;
+}

package/src/converters/ToUpperCaseConverter.ts

@@ -0,0 +1,4 @@
+export class ToUpperCaseConverter {
+  convert = (from: string) => from.toUpperCase();
+  reverseConvert = (to: string) => to;
+}

package/src/converters/TypeConverter.ts

@@ -0,0 +1,6 @@
+import type { Cells } from "./Cell.ts";
+
+export abstract class TypeConverter<To = Cells, From = Cells> {
+  abstract convert(from: From): To;
+  abstract reverseConvert(to: To): From;
+}

package/src/createCRUDRepositoryOptions.ts

@@ -0,0 +1,21 @@
+import type { Cell } from "./converters/Cell.ts";
+import type { Constructable } from "./converters/Constructable.ts";
+import type { TypeConverter } from "./converters/TypeConverter.ts";
+import type { CRUDRepositoryOptions } from "./CRUDRepositoryOptions.ts";
+import {
+  createReadonlyRepositoryMappingOptions,
+  fieldNamesOf,
+} from "./createReadonlyRepositoryMappingOptions.ts";
+
+export { fieldNamesOf } from "./createReadonlyRepositoryMappingOptions.ts";
+
+export const defaultId = (fields: string[]): string[] =>
+  fields.includes("id") ? ["id"] : fields.includes("Id") ? ["Id"] : [];
+
+export const createCRUDRepositoryOptions = <T>(
+  type: Constructable<T>,
+  rowTypeConverters?: Record<string, TypeConverter<Cell, Cell>>,
+): CRUDRepositoryOptions<T> => ({
+  ...createReadonlyRepositoryMappingOptions(type, rowTypeConverters),
+  ids: defaultId(fieldNamesOf(type)),
+});

package/src/createReadonlyRepositoryMappingOptions.ts

@@ -0,0 +1,26 @@
+import type { Cell } from "./converters/Cell.ts";
+import type { Constructable } from "./converters/Constructable.ts";
+import type { TypeConverter } from "./converters/TypeConverter.ts";
+import type { ReadonlyRepositoryMappingOptions } from "./ReadonlyRepositoryMappingOptions.ts";
+
+type FieldSource = Record<string, string | number | boolean | bigint | null | object>;
+
+export const fieldNamesOf = <T>(type: Constructable<T>): string[] => {
+  const instance = new type() as FieldSource;
+  return Object.keys(instance).filter((key) => {
+    const value = instance[key];
+    if (Array.isArray(value)) return false;
+    if (value !== null && typeof value === "object" && !(value instanceof Date) && !(value instanceof Uint8Array))
+      return "id" in value || "Id" in value;
+    return true;
+  });
+};
+
+export const createReadonlyRepositoryMappingOptions = <T>(
+  type: Constructable<T>,
+  rowTypeConverters?: Record<string, TypeConverter<Cell, Cell>>,
+): ReadonlyRepositoryMappingOptions<T> => ({
+  type,
+  entity: type.name,
+  rowTypeConverters,
+});

package/src/dotEnv.ts

@@ -0,0 +1,16 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { DatasourceOptions } from "./DatasourceOptions.ts";
+
+export const DotEnv = {
+  parse: (text: string): DatasourceOptions =>
+    Object.fromEntries(
+      text
+        .split(/\r?\n/)
+        .map((raw) => raw.trimStart().split("=", 2))
+        .filter((parts): parts is [string, string] =>
+          parts.length === 2 && !parts[0].startsWith("#") && parts[0].trim() !== "")
+        .map(([key, value]) => [key.trim(), value]),
+    ),
+  load: (path = ".env"): DatasourceOptions =>
+    existsSync(path) ? DotEnv.parse(readFileSync(path, "utf8")) : {},
+};