@knaw-huc/text-annotation-segmenter 0.5.1 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@knaw-huc/text-annotation-segmenter.svg?color=green)](https://www.npmjs.com/package/@knaw-huc/text-annotation-segmenter)
 
-Utility functions to render annotations with character offsets in a text.
+Utility functions to render annotations with character position offsets in a text.
 
 Annotations on a text have a non-hierarchical nature, i.e., they can overlap:
 ```text
@@ -24,16 +24,16 @@ The `segment` function creates an array of segments: a flat, non-overlapping lis
 
 ### Functions
 
-- [`segment<T>(text, annotations, getOffsets, getMarkerPosition?): TextSegment<T>[]`](./src/segment.ts) <br /> Split a text into TextSegments with character offsets to the text and a list of applying annotations.
+- [`segment<T>(text, annotations, getOffsets, getMarkerPosition?): TextSegment<T>[]`](./src/segment.ts) <br /> Split a text into TextSegments with character positions and a list of applying annotations.
 - [`groupSegments<T>(segments, isGroup, getId): SegmentGroup<T>[]`](src/groupSegments.ts) <br /> Recursively group segments into higher-level units (e.g., words, paragraphs, divs) by collecting all segments that share a matching annotation.
 - [`collectGroupSegments<T>(group): TextSegment<T>[]`](src/groupSegments.ts) <br /> Recursively collect all TextSegments from a Group.
-- [`findSegmentOffsets<T>(segments): Map<T, SegmentOffsets>`](src/findSegmentOffsets.ts) <br /> For each annotation, collect the first and last segment index it appears in, keyed by object reference.
+- [`findSegmentRange<T>(segments): Map<T, SegmentRange>`](src/findSegmentRange.ts) <br /> For each annotation, collect the first and last segment index it appears in, keyed by object reference.
 
 ### Types
 
 - [`SegmentGroup<T>`](src/groupSegments.ts) <br /> A `Group<T>` (with annotation and recursive children) or `Ungrouped<T>` (with plain segments).
-- [`SegmentOffsets`](src/findSegmentOffsets.ts) <br /> Start and end segment index of an annotation (excluding end segment).
-- [`TextSegment<T>`](./src/Model.ts) <br /> Start and end offsets of text segment (excluding last character), plus the annotations that apply.
+- [`SegmentRange`](src/findSegmentRange.ts) <br /> Start and end segment index of an annotation (excluding last segment).
+- [`TextSegment<T>`](./src/Model.ts) <br /> Start and end positions of text segment (excluding last character), plus the annotations that apply.
 
 ## Examples
 
@@ -51,17 +51,17 @@ annotation bc:   __
 import {segment} from "@knaw-huc/text-annotation-segmenter";
 
 const text = 'abc';
-const ab = {id: 'ab', begin: 0, end: 2};
-const bc = {id: 'bc', begin: 1, end: 3};
+const ab = {id: 'ab', start: 0, end: 2};
+const bc = {id: 'bc', start: 1, end: 3};
 
 const getOffsets = annotation => annotation;
 
 const segments = segment(text, [ab, bc], getOffsets);
 
 expect(segments).toEqual([
-  {index: 0, begin: 0, end: 1, body: 'a', annotations: [ab]},
-  {index: 1, begin: 1, end: 2, body: 'b', annotations: [ab, bc]},
-  {index: 2, begin: 2, end: 3, body: 'c', annotations: [bc]},
+  {index: 0, start: 0, end: 1, value: 'a', annotations: [ab]},
+  {index: 1, start: 1, end: 2, value: 'b', annotations: [ab, bc]},
+  {index: 2, start: 2, end: 3, value: 'c', annotations: [bc]},
 ]);
 ```
 - More examples: [segment.spec.ts](./src/segment.spec.ts).
@@ -83,8 +83,8 @@ paragraph:  __
 import {segment, groupSegments} from "@knaw-huc/text-annotation-segmenter";
 
 const text = 'aabb';
-const section = {id: 'section', type: 'section', begin: 0, end: 4};
-const paragraph = {id: 'paragraph', type: 'paragraph', begin: 0, end: 2};
+const section = {id: 'section', type: 'section', start: 0, end: 4};
+const paragraph = {id: 'paragraph', type: 'paragraph', start: 0, end: 2};
 
 const getOffsets = annotation => annotation;
 const segments = segment(text, [section, paragraph], getOffsets);
@@ -125,19 +125,19 @@ annotation b:        _
 
 ```ts
 const text = 'ab';
-const marker: Annotation = {begin: 1, end: 1, id: 'm'};
-const a: Annotation = {begin: 0, end: 1, id: 'a'};
-const b: Annotation = {begin: 1, end: 2, id: 'b'};
+const marker: Annotation = {start: 1, end: 1, id: 'm'};
+const a: Annotation = {start: 0, end: 1, id: 'a'};
+const b: Annotation = {start: 1, end: 2, id: 'b'};
 
 const segments = segment(text, [marker, a, b], getOffsets);
 const markerSegment = segments[1];
 expect(markerSegment).toEqual(
-  {index: 1, begin: 1, end: 1, body: '', annotations: [marker, a]},
+  {index: 1, start: 1, end: 1, value: '', annotations: [marker, a]},
 );
 ```
-Notice how the marker is 'postfixed' to the previous annotation. When the marker shares its character index with the start and end offsets of annotations, by default the marker segment will only include the annotations that end at that offset (e.g: a note at the end of a paragraph).
+Notice how the marker is 'postfixed' to the previous annotation. When the marker shares its character index with the start and end positions of annotations, by default the marker segment will only include the annotations that end at that position (e.g: a note at the end of a paragraph).
 
-However, markers can also be prefixed to annotations that share their start offset with the marker, using the `getMarkerPosition` parameter of the `segment` function:
+However, markers can also be prefixed to annotations that share their start position with the marker, using the `getMarkerPosition` parameter of the `segment` function:
 
 ```ts
 const getMarkerPosition = a => a.id === 'm' ? 'prefix' : 'postfix'
@@ -145,7 +145,7 @@ const segments = segment(text, [marker, a, b], getOffsets, getMarkerPosition);
 
 const markerSegment = segments[1];
 expect(markerSegment).toEqual(
-  {index: 1, begin: 1, end: 1, body: '', annotations: [marker, b]},
+  {index: 1, start: 1, end: 1, value: '', annotations: [marker, b]},
 );
 ```
 More examples: [segment.spec.ts](./src/segment.spec.ts#L118).

package/dist/GetOffsets.d.ts

@@ -1,2 +1,2 @@
-import { Offsets } from './Model.ts';
-export type GetOffsets<T> = (annotation: T) => Offsets;
+import { TextPosition } from './Model.ts';
+export type GetOffsets<T> = (annotation: T) => TextPosition;

package/dist/Model.d.ts

@@ -1,17 +1,23 @@
 /**
  * Start and end character, end excluding last character
  */
-export type Offsets = {
-    begin: number;
+export type TextPosition = {
+    start: number;
     end: number;
 };
 /**
- * Output: start and end offsets of text segment (excluding last character), plus the annotations that apply.
+ * Output: the character range and sliced text of a text segment, plus all annotations that apply.
  */
-export type TextSegment<T> = Offsets & {
+export type TextSegment<T> = TextPosition & {
     index: SegmentIndex;
-    body: string;
+    value: string;
     annotations: T[];
 };
 export type SegmentIndex = number;
-export type MarkerPosition = 'prefix' | 'postfix';
+/**
+ * Start and end segment index of an annotation, excluding last segment
+ */
+export type SegmentRange = {
+    startSegment: number;
+    endSegment: number;
+};

package/dist/findSegmentRange.d.ts

@@ -0,0 +1,6 @@
+import { SegmentRange, TextSegment } from './Model';
+/**
+ * For each annotation, collect the first and last segment index it appears in,
+ * keyed by object reference.
+ */
+export declare function findSegmentRange<T>(segments: TextSegment<T>[]): Map<T, SegmentRange>;

package/dist/index.d.ts

@@ -1,10 +1,8 @@
 export { segment } from './segment.ts';
 export type { AnnotationSegmentsByChar } from './segment.ts';
-export { findSegmentOffsets } from './findSegmentOffsets.ts';
-export type { SegmentOffsets } from './findSegmentOffsets.ts';
+export { findSegmentRange } from './findSegmentRange.ts';
 export { groupSegments } from './groupSegments.ts';
 export { collectGroupSegments } from './collectGroupSegments.ts';
 export type { Group, SegmentGroup } from './groupSegments.ts';
-export type { Offsets, TextSegment, SegmentIndex, MarkerPosition, } from './Model.ts';
+export type { TextPosition, TextSegment, SegmentIndex, SegmentRange } from './Model.ts';
 export type { GetOffsets } from './GetOffsets.ts';
-export type { GetMarkerPosition } from './GetMarkerPosition.ts';

package/dist/index.js

@@ -1,22 +1,16 @@
-function segment(text, annotations, getOffsets, getMarkerPosition = () => "postfix") {
+function segment(text, annotations, getOffsets) {
   const segments = [];
   let segmentCounter = -1;
   const offsetMap = /* @__PURE__ */ new Map(), getOrCreateOffset = (charIndex) => {
     let offset = offsetMap.get(charIndex);
     return offset || (offset = { charIndex, starting: [], ending: [] }, offsetMap.set(charIndex, offset)), offset;
-  }, createMarkerSegment = (markers, charIndex) => ({
-    index: ++segmentCounter,
-    begin: charIndex,
-    end: charIndex,
-    body: "",
-    annotations: [...markers, ...activeAnnotations]
-  });
+  };
   getOrCreateOffset(0), getOrCreateOffset(text.length);
   for (const annotation of annotations) {
-    const offsets = getOffsets(annotation), isMarker = offsets.begin === offsets.end;
-    if (isMarker && (offsets.end < 0 || offsets.begin > text.length) || !isMarker && (offsets.end <= 0 || offsets.begin >= text.length))
+    const offsets = getOffsets(annotation), isMarker = offsets.start === offsets.end;
+    if (isMarker && (offsets.end < 0 || offsets.start > text.length) || !isMarker && (offsets.end <= 0 || offsets.start >= text.length))
       continue;
-    const begin = Math.max(0, offsets.begin), end = Math.min(text.length, offsets.end);
+    const begin = Math.max(0, offsets.start), end = Math.min(text.length, offsets.end);
     getOrCreateOffset(begin).starting.push(annotation), getOrCreateOffset(end).ending.push(annotation);
   }
   const sortedOffsets = [...offsetMap.values()].sort(
@@ -28,31 +22,34 @@ function segment(text, annotations, getOffsets, getMarkerPosition = () => "postf
       const index = ++segmentCounter;
       segments.push({
         index,
-        begin: lastOffset,
+        start: lastOffset,
         end: offset.charIndex,
-        body: text.slice(lastOffset, offset.charIndex),
+        value: text.slice(lastOffset, offset.charIndex),
         annotations: [...activeAnnotations]
       });
     }
     lastOffset = offset.charIndex;
-    const postfixMarkers = [], prefixMarkers = [];
-    for (const annotation of offset.starting)
-      offset.ending.includes(annotation) && (getMarkerPosition(annotation) === "prefix" ? prefixMarkers.push(annotation) : postfixMarkers.push(annotation));
-    postfixMarkers.length && segments.push(createMarkerSegment(postfixMarkers, offset.charIndex));
+    const markers = [];
     for (const annotation of offset.starting)
-      offset.ending.includes(annotation) || activeAnnotations.add(annotation);
+      offset.ending.includes(annotation) ? markers.push(annotation) : activeAnnotations.add(annotation);
+    markers.length && segments.push({
+      index: ++segmentCounter,
+      start: offset.charIndex,
+      end: offset.charIndex,
+      value: "",
+      annotations: [...markers, ...activeAnnotations]
+    });
     for (const annotation of offset.ending)
       activeAnnotations.delete(annotation);
-    prefixMarkers.length && segments.push(createMarkerSegment(prefixMarkers, offset.charIndex));
   }
   return segments;
 }
-function findSegmentOffsets(segments) {
+function findSegmentRange(segments) {
   const offsets = /* @__PURE__ */ new Map();
   for (let i = 0; i < segments.length; i++)
     for (const annotation of segments[i].annotations) {
       const existing = offsets.get(annotation);
-      existing ? existing.endSegment = i + 1 : offsets.set(annotation, { beginSegment: i, endSegment: i + 1 });
+      existing ? existing.endSegment = i + 1 : offsets.set(annotation, { startSegment: i, endSegment: i + 1 });
     }
   return offsets;
 }
@@ -102,7 +99,7 @@ function collectGroupSegments(group2) {
 }
 export {
   collectGroupSegments,
-  findSegmentOffsets,
+  findSegmentRange,
   groupSegments,
   segment
 };

package/dist/segment.d.ts

@@ -1,6 +1,5 @@
 import { TextSegment } from './Model';
 import { GetOffsets } from './GetOffsets.ts';
-import { GetMarkerPosition } from './GetMarkerPosition.ts';
 /**
  * Split a text into {@link TextSegment}s with character offsets and a list of applying annotations.
  *
@@ -10,19 +9,10 @@ import { GetMarkerPosition } from './GetMarkerPosition.ts';
  *
  * @param getOffsets Find the character begin and end index of an annotation
  *
- * @param getMarkerPosition Should a marker segment be prefixed or postfixed?
- * - 'prefix': include annotations that start at marker offset
- * - 'postfix': include annotations that end at marker offset
- *
- * For example, consider two paragraphs: <p1>aa</p1><marker/><p2>bb</p2>
- * The annotation <marker/> shares the end character index with annotation <p1>,
- * and the begin character index with annotation <p2>:
- * - with 'postfix': segment (2,2) will contain annotations [marker, p1]
- * - with 'prefix': segment (2,2) will contain annotations [marker, p2]
- *
- * By default, markers are postfixed.
+ * Marker segments include all annotations present at that position:
+ * ending, spanning, and starting. Consumers can filter these as needed.
  */
-export declare function segment<T>(text: string, annotations: T[], getOffsets: GetOffsets<T>, getMarkerPosition?: GetMarkerPosition<T>): TextSegment<T>[];
+export declare function segment<T>(text: string, annotations: T[], getOffsets: GetOffsets<T>): TextSegment<T>[];
 export type AnnotationSegmentsByChar<T> = {
     charIndex: number;
     starting: T[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knaw-huc/text-annotation-segmenter",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/knaw-huc/text-annotation-segmenter.git"

package/dist/GetMarkerPosition.d.ts

@@ -1,2 +0,0 @@
-import { MarkerPosition } from './Model.ts';
-export type GetMarkerPosition<T> = (a: T) => MarkerPosition;

package/dist/findSegmentOffsets.d.ts

@@ -1,13 +0,0 @@
-import { TextSegment } from './Model';
-export type SegmentOffsets = {
-    beginSegment: number;
-    /**
-     * Excluding last segment
-     */
-    endSegment: number;
-};
-/**
- * For each annotation, collect the first and last segment index
- * it appears in, keyed by object reference.
- */
-export declare function findSegmentOffsets<T>(segments: TextSegment<T>[]): Map<T, SegmentOffsets>;