@scoutmesh/viewer 0.2.0

package/dist/store.js

@@ -0,0 +1,437 @@
+import { createHash, randomUUID } from "node:crypto";
+
+import { InputError } from "./input-error.js";
+import { readStateFile, writeStateFile } from "./state-file.js";
+                                                                
+
+function isObject(value         )                                   {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isStrings(value         )                    {
+  return (
+    Array.isArray(value) &&
+    value.every((item         ) => typeof item === "string")
+  );
+}
+
+function object(value         )                          {
+  if (!isObject(value)) {
+    throw new InputError("Expected a JSON object.");
+  }
+  return value;
+}
+
+function label(value         , field        , max = 200)         {
+  if (typeof value !== "string" || !value.trim() || value.length > max) {
+    throw new InputError(
+      `${field} must be a nonempty string of at most ${max} characters.`
+    );
+  }
+  return value;
+}
+
+function strings(value         , field        )           {
+  if (!isStrings(value)) {
+    throw new InputError(`${field} must be an array of strings.`);
+  }
+  return value;
+}
+
+function layout(value         )         {
+  const input = object(value);
+  if (input.type !== "table" && input.type !== "cards") {
+    throw new InputError("layout.type must be table or cards.");
+  }
+  const columns = strings(input.columns, "layout.columns");
+  if (
+    columns.length < 1 ||
+    columns.length > 12 ||
+    new Set(columns).size !== columns.length ||
+    columns.some((key) => !/^[a-zA-Z][\w]{0,49}$/u.test(key))
+  ) {
+    throw new InputError("Choose 1–12 unique field names for layout.columns.");
+  }
+  return { columns, type: input.type };
+}
+
+function cellValue(cell         , key        )       {
+  if (
+    cell === null ||
+    typeof cell === "boolean" ||
+    (typeof cell === "number" && Number.isFinite(cell)) ||
+    (typeof cell === "string" && cell.length <= 20_000) ||
+    (isStrings(cell) &&
+      cell.length <= 100 &&
+      cell.every((entry) => entry.length <= 2000))
+  ) {
+    return cell;
+  }
+  throw new InputError(
+    `Unsupported value for ${key}. Use scalar values or string arrays.`
+  );
+}
+
+function records(value         , previous              = [])              {
+  if (!Array.isArray(value) || value.length > 2000) {
+    throw new InputError(
+      "records must be an array with at most 2,000 candidates."
+    );
+  }
+  const result = new Map(previous.map((record) => [record.id, record]));
+  for (const item of value) {
+    const input = object(item);
+    const id = label(input.id, "Candidate id");
+    const prior = result.get(id);
+    const merged            = {
+      ...prior,
+      id,
+      name: label(input.name ?? prior?.name, "Candidate name"),
+    };
+    for (const [key, cell] of Object.entries(input)) {
+      if (
+        !/^[a-zA-Z][\w]{0,49}$/u.test(key) ||
+        ["constructor", "prototype"].includes(key)
+      ) {
+        throw new InputError(
+          "Candidate field names must be simple identifiers."
+        );
+      }
+      merged[key] = cellValue(cell, key);
+    }
+    label(merged.name, "Candidate name");
+    result.set(id, merged);
+  }
+  if (result.size > 2000) {
+    throw new InputError("A prototype view supports at most 2,000 candidates.");
+  }
+  return [...result.values()];
+}
+
+function savedHistory(pairs           ) {
+  const history = new Map                ();
+  for (const pair of pairs) {
+    if (
+      !Array.isArray(pair) ||
+      pair.length !== 2 ||
+      typeof pair[0] !== "string" ||
+      typeof pair[1] !== "string" ||
+      !/^[a-f0-9]{64}$/u.test(pair[1]) ||
+      history.has(pair[0])
+    ) {
+      throw new Error("Invalid saved update fingerprint.");
+    }
+    history.set(label(pair[0], "updateId"), pair[1]);
+  }
+  return history;
+}
+
+export class ViewStore {
+          views = new Map              ();
+          updates = new Map                             ();
+
+                   stateFile                    ;
+
+  constructor(stateFile         ) {
+    this.stateFile = stateFile;
+    if (stateFile) {
+      const saved = readStateFile(stateFile);
+      if (saved !== undefined) {
+        try {
+          this.load(saved);
+        } catch (error) {
+          throw new Error(
+            `Invalid viewer state in ${stateFile}. The file has not been changed.`,
+            { cause: error }
+          );
+        }
+      }
+    }
+  }
+
+  snapshot() {
+    return structuredClone({
+      updates: [...this.updates].map(([id, history]) => [id, [...history]]),
+      version: 1,
+      views: [...this.views.values()],
+    });
+  }
+
+          load(value         ) {
+    const input = object(value);
+    if (
+      input.version !== 1 ||
+      !Array.isArray(input.views) ||
+      !Array.isArray(input.updates)
+    ) {
+      throw new Error("Unsupported viewer state format.");
+    }
+    const staging = new ViewStore();
+    for (const saved of input.views) {
+      const entry = object(saved);
+      const view = staging.create(entry);
+      staging.select(view.id, entry.state);
+      if (
+        typeof entry.revision !== "number" ||
+        !Number.isSafeInteger(entry.revision) ||
+        entry.revision < 1 ||
+        typeof entry.updatedAt !== "string" ||
+        !Number.isFinite(Date.parse(entry.updatedAt))
+      ) {
+        throw new Error("Invalid saved revision or timestamp.");
+      }
+      const restored = staging.get(view.id);
+      restored.revision = entry.revision;
+      restored.updatedAt = entry.updatedAt;
+      staging.views.set(view.id, restored);
+    }
+    const seen = new Set();
+    for (const entry of input.updates) {
+      if (
+        !Array.isArray(entry) ||
+        entry.length !== 2 ||
+        typeof entry[0] !== "string" ||
+        !staging.views.has(entry[0]) ||
+        seen.has(entry[0]) ||
+        !Array.isArray(entry[1]) ||
+        entry[1].length > 500
+      ) {
+        throw new Error("Invalid saved update history.");
+      }
+      const history = savedHistory(entry[1]);
+      staging.updates.set(entry[0], history);
+      seen.add(entry[0]);
+    }
+    this.views = staging.views;
+    this.updates = staging.updates;
+  }
+
+          commit(views                   , updates = this.updates) {
+    if (this.stateFile) {
+      try {
+        writeStateFile(this.stateFile, {
+          updates: [...updates].map(([id, history]) => [id, [...history]]),
+          version: 1,
+          views: [...views.values()],
+        });
+      } catch {
+        throw new InputError(
+          "Could not save viewer state. The change was not applied. Check the local state file and available disk space.",
+          503
+        );
+      }
+    }
+    this.views = views;
+    this.updates = updates;
+  }
+
+          saveView(view      , history                      ) {
+    const views = new Map([...this.views, [view.id, view]]);
+    const updates = new Map(this.updates);
+    if (history) {
+      updates.set(view.id, history);
+    }
+    this.commit(views, updates);
+    return this.get(view.id);
+  }
+
+  list() {
+    return [...this.views.values()].map(({ id, title, revision, records }) => ({
+      count: records.length,
+      id,
+      revision,
+      title,
+    }));
+  }
+
+  get(id        )       {
+    const view = this.views.get(id);
+    if (!view) {
+      throw new InputError(
+        "View not found. Check the view ID and configured state file.",
+        404
+      );
+    }
+    return structuredClone(view);
+  }
+
+  create(value         )       {
+    const input = object(value);
+    if (this.views.size >= 20) {
+      throw new InputError(
+        "The prototype supports at most 20 open views.",
+        409
+      );
+    }
+    const id =
+      input.id === undefined ? randomUUID() : label(input.id, "View id", 80);
+    if (!/^[\w-]+$/u.test(id)) {
+      throw new InputError(
+        "View id may contain only letters, numbers, underscores, and hyphens."
+      );
+    }
+    if (this.views.has(id)) {
+      throw new InputError(
+        "View already exists. PATCH it to send another batch.",
+        409
+      );
+    }
+    const view       = {
+      id,
+      layout: layout(
+        input.layout ?? {
+          columns: ["name", "role", "company", "location"],
+          type: "table",
+        }
+      ),
+      records: records(input.records ?? []),
+      revision: 1,
+      state: {
+        filter: "",
+        maybeIds: [],
+        removedIds: [],
+        selectedIds: [],
+        sortBy: "name",
+        sortDirection: "asc",
+      },
+      title: label(input.title, "Title"),
+      updatedAt: new Date().toISOString(),
+    };
+    return this.saveView(view, new Map());
+  }
+
+  update(id        , value         )       {
+    const input = object(value);
+    const current = this.get(id);
+    const updateId = label(input.updateId, "updateId");
+    const fingerprint = createHash("sha256")
+      .update(JSON.stringify(input))
+      .digest("hex");
+    const priorHistory = this.updates.get(id);
+    if (!priorHistory) {
+      throw new InputError("View not found.", 404);
+    }
+    const history = new Map(priorHistory);
+    if (history.has(updateId)) {
+      if (history.get(updateId) !== fingerprint) {
+        throw new InputError(
+          "This updateId was already used with a different payload.",
+          409
+        );
+      }
+      return current;
+    }
+    if (
+      input.expectedRevision !== undefined &&
+      input.expectedRevision !== current.revision
+    ) {
+      throw new InputError(
+        `Revision conflict. Current revision is ${current.revision}.`,
+        409
+      );
+    }
+    if (input.operation === "upsert") {
+      current.records = records(input.records, current.records);
+    } else if (input.operation === "replace") {
+      current.records = records(input.records);
+    } else if (input.operation === "remove") {
+      const ids = new Set(strings(input.ids, "ids"));
+      current.records = current.records.filter((record) => !ids.has(record.id));
+    } else if (input.operation !== "set_layout") {
+      throw new InputError(
+        "operation must be upsert, replace, remove, or set_layout."
+      );
+    }
+    if (input.layout !== undefined || input.operation === "set_layout") {
+      current.layout = layout(input.layout);
+    }
+    if (input.title !== undefined) {
+      current.title = label(input.title, "Title");
+    }
+    const ids = new Set(current.records.map((record) => record.id));
+    current.state.selectedIds = current.state.selectedIds.filter((id) =>
+      ids.has(id)
+    );
+    current.state.maybeIds = current.state.maybeIds.filter((id) => ids.has(id));
+    current.state.removedIds = current.state.removedIds.filter((id) =>
+      ids.has(id)
+    );
+    current.revision += 1;
+    current.updatedAt = new Date().toISOString();
+    history.set(updateId, fingerprint);
+    if (history.size > 500) {
+      const oldest = history.keys().next().value;
+      if (oldest !== undefined) {
+        history.delete(oldest);
+      }
+    }
+    return this.saveView(current, history);
+  }
+
+  select(id        , value         )       {
+    const input = object(value);
+    const current = this.get(id);
+    const ids = new Set(current.records.map((record) => record.id));
+    const selectedIds = [...new Set(strings(input.selectedIds, "selectedIds"))];
+    const removedIds = [
+      ...new Set(
+        strings(input.removedIds ?? current.state.removedIds, "removedIds")
+      ),
+    ];
+    const maybeIds = [
+      ...new Set(strings(input.maybeIds ?? current.state.maybeIds, "maybeIds")),
+    ];
+    if (
+      [...selectedIds, ...removedIds, ...maybeIds].some((id) => !ids.has(id))
+    ) {
+      throw new InputError(
+        "Selection includes a candidate that is no longer in this view.",
+        409
+      );
+    }
+    if (
+      typeof input.filter !== "string" ||
+      input.filter.length > 500 ||
+      typeof input.sortBy !== "string" ||
+      input.sortBy.length > 50 ||
+      (input.sortDirection !== "asc" && input.sortDirection !== "desc")
+    ) {
+      throw new InputError("Invalid filter or sort state.");
+    }
+    if (selectedIds.some((id) => removedIds.includes(id))) {
+      throw new InputError(
+        "A removed candidate cannot also be shortlisted.",
+        409
+      );
+    }
+    if (
+      maybeIds.some(
+        (candidateId) =>
+          selectedIds.includes(candidateId) || removedIds.includes(candidateId)
+      )
+    ) {
+      throw new InputError(
+        "A candidate can have only one review decision: shortlisted, maybe, or removed.",
+        409
+      );
+    }
+    current.state = {
+      filter: input.filter,
+      maybeIds,
+      removedIds,
+      selectedIds,
+      sortBy: input.sortBy,
+      sortDirection: input.sortDirection,
+    };
+    return this.saveView(current);
+  }
+
+  delete(id        ) {
+    this.get(id);
+    const views = new Map(this.views);
+    const updates = new Map(this.updates);
+    views.delete(id);
+    updates.delete(id);
+    this.commit(views, updates);
+  }
+}