linked-rolls 0.14.0 → 0.15.0

package/lib/editionOps.d.ts

@@ -7,6 +7,7 @@ import { Edit } from "./Edit";
 import { RollCopy, ScaleReading, Shift } from "./RollCopy";
 import { FeatureSource } from "./FeatureSource";
 import { AnyArgumentation, Certainty } from "./Assumption";
+import { AnyFeature } from "./Feature";
 /**
  * A change to an edition, written onto an immer draft of it. One
  * operation is one undo step, so an operation that has to read the
@@ -44,6 +45,28 @@ export declare const removeFeatures: (copyId: string, featureIds: readonly strin
  * carries, and with every reference the versions made to those symbols.
  */
 export declare const removeCopy: (copyId: string) => EditionOp;
+/** Why several features cannot be replaced by one. */
+export type MergeObstacle = 'fewer-than-two' | 'different-types' | 'different-tracks' | 'differing-conditions' | 'unlike-features';
+/**
+ * What stands in the way of reading the features as one, or nothing
+ * where they may be merged. Features may be merged where they differ
+ * in nothing but their place along the roll, their depiction and the
+ * condition at most one of them states. How far apart they lie is not
+ * asked: whether a gap is a bridge of the perforator, a tear or two
+ * perforations of their own is the editor's reading.
+ */
+export declare const mergeObstacle: (features: readonly AnyFeature[]) => MergeObstacle | undefined;
+/**
+ * Replaces the features of the copy with a single one covering them
+ * all, where a scan has split what the editor reads as one feature.
+ * The merged feature takes the place of the first it replaces and
+ * spans from the first to the last, any gap between them included.
+ * What the replaced features carried is carried by the merged one.
+ *
+ * Throws where the features cannot stand for one; `mergeObstacle`
+ * says beforehand whether they can.
+ */
+export declare const mergeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;
 /**
  * Bases the child on the parent. A symbol of the child that collates
  * with one the parent hands down adds its carriers to that symbol; the

package/lib/editionOps.js

@@ -173,6 +173,117 @@ export const removeCopy = (copyId) => onCopy(copyId, (copy, draft) => {
     forgetFeatures(draft, featureIdsOf(copy));
     draft.copies = draft.copies.filter(c => c.id !== copyId);
 });
+const isRecord = (value) => typeof value === 'object' && value !== null;
+/**
+ * Whether two records of the edition state the same, the identity of a
+ * statement left out: two transcriptions reading the same word say the
+ * same, whichever ids they were given.
+ */
+const sayTheSame = (a, b) => {
+    if (a === b)
+        return true;
+    if (!isRecord(a) || !isRecord(b) || Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    keys.delete('id');
+    return [...keys].every(key => sayTheSame(a[key], b[key]));
+};
+/** What a feature states beyond its identity, its place along the roll, its depiction and its condition. */
+const nature = (feature) => {
+    const { id, horizontal, depiction, condition, ...rest } = feature;
+    return rest;
+};
+const conditionsOf = (features) => features.flatMap(feature => feature.condition ? [feature.condition] : []);
+/**
+ * What stands in the way of reading the features as one, or nothing
+ * where they may be merged. Features may be merged where they differ
+ * in nothing but their place along the roll, their depiction and the
+ * condition at most one of them states. How far apart they lie is not
+ * asked: whether a gap is a bridge of the perforator, a tear or two
+ * perforations of their own is the editor's reading.
+ */
+export const mergeObstacle = (features) => {
+    if (features.length < 2)
+        return 'fewer-than-two';
+    const [first, ...rest] = features;
+    if (rest.some(feature => feature.type !== first.type))
+        return 'different-types';
+    if (rest.some(feature => !sayTheSame(feature.vertical, first.vertical)))
+        return 'different-tracks';
+    if (rest.some(feature => !sayTheSame(nature(feature), nature(first))))
+        return 'unlike-features';
+    const conditions = conditionsOf(features);
+    if (conditions.some(condition => !sayTheSame(condition, conditions[0])))
+        return 'differing-conditions';
+    return undefined;
+};
+/** The items with the replacement in the place of the first it stands for, the others dropped. */
+const standingFor = (items, stands, replacement) => {
+    const first = items.findIndex(stands);
+    if (first < 0)
+        return items;
+    return items.flatMap((item, i) => i === first ? [replacement] : stands(item) ? [] : [item]);
+};
+const spanning = (features) => ({
+    unit: 'mm',
+    from: mm(Math.min(...features.map(feature => feature.horizontal.from))),
+    to: mm(Math.max(...features.map(feature => feature.horizontal.to)))
+});
+/**
+ * The feature the merged ones give way to. It spans them all and is in
+ * every other respect the one of them that states a condition, the
+ * others being alike in all but their place. The depiction goes: a
+ * region of the scan showing one part depicts no more than that part.
+ */
+const mergedFrom = (features) => {
+    const stating = features.find(feature => feature.condition) ?? features[0];
+    const merged = { ...stating, id: v4(), horizontal: spanning(features) };
+    delete merged.depiction;
+    return merged;
+};
+/** The symbol carried by the merged feature where it named one of those it replaces, and naming it once. */
+const carriedByMerged = (replaced, mergedId) => (symbol) => {
+    const names = (carrier) => replaced.has(idOf(carrier));
+    const first = symbol.carriers.find(names);
+    if (!first)
+        return symbol;
+    return { ...symbol, carriers: standingFor(symbol.carriers, names, { ...first, id: mergedId }) };
+};
+/** Points the versions at the merged feature wherever they name one it replaces. */
+const carryOver = (draft, replaced, mergedId) => {
+    const recarry = carriedByMerged(replaced, mergedId);
+    const recarrying = (edit) => {
+        const insert = edit.insert && mapped(edit.insert, recarry);
+        return insert === edit.insert ? edit : { ...edit, insert };
+    };
+    const versions = stateOf(draft.versions);
+    draft.versions.forEach((version, i) => {
+        version.edits = mapped(versions[i].edits, recarrying);
+    });
+};
+/**
+ * Replaces the features of the copy with a single one covering them
+ * all, where a scan has split what the editor reads as one feature.
+ * The merged feature takes the place of the first it replaces and
+ * spans from the first to the last, any gap between them included.
+ * What the replaced features carried is carried by the merged one.
+ *
+ * Throws where the features cannot stand for one; `mergeObstacle`
+ * says beforehand whether they can.
+ */
+export const mergeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draft) => {
+    const replaced = new Set(featureIds);
+    const isReplaced = (feature) => replaced.has(feature.id);
+    const features = stateOf(copy.features);
+    const toMerge = features.filter(isReplaced);
+    const obstacle = mergeObstacle(toMerge);
+    if (obstacle) {
+        throw new Error(`The features of copy ${copyId} cannot be merged: ${obstacle}`);
+    }
+    const merged = mergedFrom(toMerge);
+    copy.features = standingFor(features, isReplaced, merged);
+    carryOver(draft, replaced, merged.id);
+});
 /** The carriers of each collated symbol pass to its counterpart. */
 const handOverCarriers = (view, draft, collations) => collations.forEach(({ symbol, counterpart }) => {
     const path = view.getPath(counterpart.id);

package/lib/index.d.ts

@@ -27,5 +27,6 @@ export * from './constraints';
 export * from './context';
 export * from './asJsonLd';
 export * from './importJsonLd';
+export * from './migrate';
 export { readFromStanfordAton, type StanfordAtonOptions } from './readers/stanfordAton';
 export { readFromSpencerBar, readSpencerAnn, paperSpeedOfSpencerAnn, SPENCER_ROWS_PER_INCH, type SpencerBarOptions } from './readers/spencerBar';

package/lib/index.js

@@ -27,5 +27,6 @@ export * from './constraints';
 export * from './context';
 export * from './asJsonLd';
 export * from './importJsonLd';
+export * from './migrate';
 export { readFromStanfordAton } from './readers/stanfordAton';
 export { readFromSpencerBar, readSpencerAnn, paperSpeedOfSpencerAnn, SPENCER_ROWS_PER_INCH } from './readers/spencerBar';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {