@eten-tech-foundation/scripture-utilities 0.1.5 → 0.1.6

package/src/converters/usj/usj-document-location.model.ts

@@ -0,0 +1,238 @@
+/** Serializable USJ locations relative to a specific USJ document (chapter or book) */
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Used in TSDoc @link references
+import type { MarkerContent, MarkerObject, Usj } from "./usj.model.js";
+
+/**
+ * A JSONPath query to a {@link MarkerContent}, {@link Usj}, or property within a USJ document and
+ * additional information that point to a specific location in that USJ document.
+ *
+ * This type does not include a verse reference because the JSONPath is relative to a specific USJ
+ * document; that USJ document may have a book, a chapter, or something else in it. Use
+ * `UsjLocation` to specify which USJ document this location is relative to, making the
+ * location an absolute verse reference location. The closest equivalent concept in USFM to this
+ * relative document location is a string character index in a USFM document; such an index is
+ * relative to a specific USFM document rather than indicating an absolute position in a Scripture
+ * text.
+ *
+ * This type intends to represent USFM positions (`UsfmVerseLocation`) in USJ space. However,
+ * there are some USFM positions that are not currently representable with these types:
+ *
+ * - The second slash in `optbreak`'s USFM representation `//` (literally not representable)
+ * - Nested marker prefix on opening markers like `+` for character markers (literally not
+ *   representable)
+ * - The bar `|` that indicates the start of closing marker attributes (no official representation)
+ * - The equals sign for closing marker attributes (no official representation)
+ * - The quotes around closing marker attribute values (no official representation)
+ * - The space between closing marker attributes (no official representation)
+ *
+ * Also note that the following types do not specify a concrete location that is actually in the USJ
+ * document but represent a USFM location relative to the most similar thing in USJ that there is:
+ *
+ * - {@link UsjClosingMarkerLocation} - there are no distinct closing objects in JSON; there is a
+ *   common syntax for closing every object, but it is only one character and is on every single
+ *   object as opposed to USFM closing markers which are multiple characters long and are only
+ *   sometimes present.
+ * - {@link UsjAttributeKeyLocation} - when the attribute whose key is being pointed to is an
+ *   attribute marker in USFM, the `keyOffset` does not apply to the USJ attribute name (e.g.
+ *   `altnumber`) but to the USFM attribute marker name (e.g. `ca`).
+ * - {@link UsjAttributeMarkerLocation} - attribute markers are just properties in JSON; they do not
+ *   have their own object such that they would have an opening that can be pointed to in the JSON
+ *   like they have their own opening in USFM.
+ * - {@link UsjClosingAttributeMarkerLocation} - attribute markers are just properties in JSON, plus
+ *   they are in the same situation as {@link UsjClosingMarkerLocation} as detailed above.
+ *
+ * To see many examples of the same point represented by both USFM and USJ locations, go to
+ * https://github.com/paranext/paranext-core/tree/main/lib/platform-bible-utils/src/scripture/usj-reader-writer-test-data/testUSFM-2SA-1-locations.ts
+ *
+ * @public
+ */
+export type UsjDocumentLocation =
+  | UsjMarkerLocation
+  | UsjClosingMarkerLocation
+  | UsjTextContentLocation
+  | UsjPropertyValueLocation
+  | UsjAttributeKeyLocation
+  | UsjAttributeMarkerLocation
+  | UsjClosingAttributeMarkerLocation;
+
+/**
+ * A JSONPath query to a {@link MarkerObject} or {@link Usj} node. Indicates the very beginning of
+ * that marker (at the backslash in USFM).
+ *
+ * @public
+ */
+export interface UsjMarkerLocation {
+  /** JSON path to the marker object the location is pointing to. */
+  jsonPath: ContentJsonPath;
+}
+
+/**
+ * A JSONPath query to a specific point in the closing marker representation of a
+ * {@link MarkerObject} or {@link Usj} node.
+ *
+ * @public
+ */
+export interface UsjClosingMarkerLocation {
+  /**
+   * JSON path to the marker object whose closing marker the location is pointing to. The offset
+   * applies to the closing marker representation of that marker (for example, `\nd*` in USFM).
+   */
+  jsonPath: ContentJsonPath;
+  /**
+   * The character index in the closing marker representation where this location is pointing. The
+   * location is at this offset within the closing marker representation.
+   */
+  closingMarkerOffset: number;
+}
+
+/**
+ * A JSONPath query to a specific point in a text content string in a {@link MarkerObject.content}
+ * array.
+ *
+ * @public
+ */
+export interface UsjTextContentLocation {
+  /**
+   * JSON path to the text content string the location is pointing to. The offset applies to this
+   * text string.
+   */
+  jsonPath: ContentJsonPath;
+  /**
+   * The character index in the text content string where this location is pointing. The location is
+   * at this offset within the text content string.
+   */
+  offset: number;
+}
+
+/**
+ * A JSONPath query to a specific point in a property (`marker` or an attribute) value string in a
+ * {@link MarkerObject} or {@link Usj}. The property cannot be `type` because `type`'s value has no
+ * representation in USFM.
+ *
+ * To represent a location in an attribute's key, use {@link UsjAttributeKeyLocation}.
+ *
+ * @public
+ */
+export interface UsjPropertyValueLocation {
+  /**
+   * JSON path to the property the location is pointing to. The offset applies to this property's
+   * value string.
+   */
+  jsonPath: PropertyJsonPath;
+  /**
+   * The character index in the property's value string where this location is pointing. The
+   * location is at this offset within the property's value string.
+   */
+  propertyOffset: number;
+}
+
+/**
+ * A JSONPath query to a specific point in an attribute key string in a {@link MarkerObject} or
+ * {@link Usj}. The property cannot be `type` or `marker` because these properties' keys have no
+ * representation in USFM. The property also cannot be any special attribute whose key doesn't have
+ * a text representation in USFM like default attribute, leading attribute, text content attribute
+ *
+ * To represent a location in an attribute's value, use {@link UsjPropertyValueLocation}.
+ *
+ * @public
+ */
+export interface UsjAttributeKeyLocation {
+  /**
+   * JSON path to the marker whose attribute key the location is pointing to. The offset applies to
+   * this attribute's key string unless the attribute is an attribute marker in USFM.
+   */
+  jsonPath: ContentJsonPath;
+  /** Attribute name on the marker object whose key this location is pointing to. */
+  keyName: string;
+  /**
+   * The character index in the attribute's key string where this location is pointing.
+   *
+   * If the attribute is an attribute marker in USFM, the location is at this offset within the
+   * marker name for this attribute marker (for example, `c`'s `altnumber` attribute has attribute
+   * marker `ca`, so its `keyOffset` applies to `ca`).
+   *
+   * If the attribute is not an attribute marker in USFM, the location is at this offset within the
+   * attribute's key string.
+   */
+  keyOffset: number;
+}
+
+/**
+ * A JSONPath query to an attribute marker derived from an attribute on a {@link MarkerObject} or
+ * {@link Usj}. Indicates the very beginning of that marker (at the backslash in USFM).
+ *
+ * @public
+ */
+export interface UsjAttributeMarkerLocation {
+  /** JSON path to the marker whose attribute marker the location is pointing to. */
+  jsonPath: ContentJsonPath;
+  /**
+   * Attribute name on the marker object whose key this location is pointing to. This attribute is
+   * an attribute marker in USFM.
+   */
+  keyName: string;
+}
+
+/**
+ * A JSONPath query to a specific point in the closing marker representation of an attribute marker
+ * derived from an attribute on a {@link MarkerObject} or {@link Usj}.
+ *
+ * @public
+ */
+export interface UsjClosingAttributeMarkerLocation {
+  /**
+   * JSON path to the marker whose attribute marker's closing marker the location is pointing to.
+   * The offset applies to the closing marker representation of that attribute marker (for example,
+   * `\ca*` in USFM).
+   */
+  jsonPath: ContentJsonPath;
+  /**
+   * Attribute name on the marker object whose key this location is pointing to. This attribute is
+   * an attribute marker in USFM.
+   */
+  keyName: string;
+  /**
+   * The character index in the closing marker representation where this location is pointing. The
+   * location is at this offset within the closing marker representation of the attribute marker.
+   */
+  keyClosingMarkerOffset: number;
+}
+
+/**
+ * JSON path to a {@link MarkerObject}, {@link Usj}, or text content string in the current USJ
+ * document.
+ *
+ * This could actually have more content clauses at the end, but TS types are limited
+ *
+ * @public
+ */
+export type ContentJsonPath =
+  | ""
+  | `$`
+  | `$.content[${number}]`
+  | `$.content[${number}].content[${number}]`
+  | `$.content[${number}].content[${number}].content[${number}]`
+  | `$.content[${number}].content[${number}].content[${number}].content[${number}]`;
+
+/**
+ * JSON path to the `marker` or an attribute on a {@link MarkerObject} or {@link Usj} in the current
+ * USJ document. Note that it seems you must use `['bracket notation']` rather than `.dot` notation
+ * if there are symbols other than underscore in the property name
+ *
+ * This could actually have more content clauses at the end, but TS types are limited
+ *
+ * @public
+ */
+export type PropertyJsonPath =
+  | ""
+  | `$.${string}`
+  | `$['${string}']`
+  | `$.content[${number}].${string}`
+  | `$.content[${number}]['${string}']`
+  | `$.content[${number}].content[${number}].${string}`
+  | `$.content[${number}].content[${number}]['${string}']`
+  | `$.content[${number}].content[${number}].content[${number}].${string}`
+  | `$.content[${number}].content[${number}].content[${number}]['${string}']`
+  | `$.content[${number}].content[${number}].content[${number}].content[${number}].${string}`
+  | `$.content[${number}].content[${number}].content[${number}].content[${number}]['${string}']`;

package/src/converters/usj/usj-document-location.utils.ts

@@ -0,0 +1,187 @@
+/**
+ * Type guards for {@link UsjDocumentLocation} subtypes.
+ *
+ * These guards enable runtime type narrowing to distinguish between the different
+ * location types in a USJ document.
+ */
+
+import type {
+  UsjDocumentLocation,
+  UsjMarkerLocation,
+  UsjClosingMarkerLocation,
+  UsjTextContentLocation,
+  UsjPropertyValueLocation,
+  UsjAttributeKeyLocation,
+  UsjAttributeMarkerLocation,
+  UsjClosingAttributeMarkerLocation,
+} from "./usj-document-location.model.js";
+
+/**
+ * Type guard to check if a location is a {@link UsjMarkerLocation}.
+ *
+ * A marker location points to the very beginning of a marker (at the backslash in USFM).
+ * It only has a `jsonPath` property with no offset properties.
+ *
+ * @param location - The location to check.
+ * @returns `true` if the location is a `UsjMarkerLocation`, `false` otherwise.
+ *
+ * @public
+ */
+export function isUsjMarkerLocation(
+  location: UsjDocumentLocation | undefined | null,
+): location is UsjMarkerLocation {
+  return (
+    location != null &&
+    "jsonPath" in location &&
+    !("offset" in location) &&
+    !("closingMarkerOffset" in location) &&
+    !("propertyOffset" in location) &&
+    !("keyName" in location)
+  );
+}
+
+/**
+ * Type guard to check if a location is a {@link UsjClosingMarkerLocation}.
+ *
+ * A closing marker location points to a specific point in the closing marker representation
+ * of a marker object (e.g., `\nd*` in USFM).
+ *
+ * @param location - The location to check.
+ * @returns `true` if the location is a `UsjClosingMarkerLocation`, `false` otherwise.
+ *
+ * @public
+ */
+export function isUsjClosingMarkerLocation(
+  location: UsjDocumentLocation | undefined | null,
+): location is UsjClosingMarkerLocation {
+  return location != null && "jsonPath" in location && "closingMarkerOffset" in location;
+}
+
+/**
+ * Type guard to check if a location is a {@link UsjTextContentLocation}.
+ *
+ * A text content location points to a specific character offset within a text content string
+ * in a marker's content array.
+ *
+ * @param location - The location to check.
+ * @returns `true` if the location is a `UsjTextContentLocation`, `false` otherwise.
+ *
+ * @public
+ */
+export function isUsjTextContentLocation(
+  location: UsjDocumentLocation | undefined | null,
+): location is UsjTextContentLocation {
+  return (
+    location != null &&
+    "jsonPath" in location &&
+    "offset" in location &&
+    !("propertyOffset" in location) &&
+    !("keyName" in location)
+  );
+}
+
+/**
+ * Type guard to check if a location is a {@link UsjPropertyValueLocation}.
+ *
+ * A property value location points to a specific character offset within a property value
+ * (such as `marker` or an attribute value).
+ *
+ * @param location - The location to check.
+ * @returns `true` if the location is a `UsjPropertyValueLocation`, `false` otherwise.
+ *
+ * @public
+ */
+export function isUsjPropertyValueLocation(
+  location: UsjDocumentLocation | undefined | null,
+): location is UsjPropertyValueLocation {
+  return location != null && "jsonPath" in location && "propertyOffset" in location;
+}
+
+/**
+ * Type guard to check if a location is a {@link UsjAttributeKeyLocation}.
+ *
+ * An attribute key location points to a specific character offset within an attribute's key string.
+ *
+ * @param location - The location to check.
+ * @returns `true` if the location is a `UsjAttributeKeyLocation`, `false` otherwise.
+ *
+ * @public
+ */
+export function isUsjAttributeKeyLocation(
+  location: UsjDocumentLocation | undefined | null,
+): location is UsjAttributeKeyLocation {
+  return (
+    location != null && "jsonPath" in location && "keyName" in location && "keyOffset" in location
+  );
+}
+
+/**
+ * Type guard to check if a location is a {@link UsjAttributeMarkerLocation}.
+ *
+ * An attribute marker location points to the beginning of an attribute marker
+ * (at the backslash in USFM, e.g., `\ca` for chapter alternate number).
+ *
+ * @param location - The location to check.
+ * @returns `true` if the location is a `UsjAttributeMarkerLocation`, `false` otherwise.
+ *
+ * @public
+ */
+export function isUsjAttributeMarkerLocation(
+  location: UsjDocumentLocation | undefined | null,
+): location is UsjAttributeMarkerLocation {
+  return (
+    location != null &&
+    "jsonPath" in location &&
+    "keyName" in location &&
+    !("keyOffset" in location) &&
+    !("keyClosingMarkerOffset" in location)
+  );
+}
+
+/**
+ * Type guard to check if a location is a {@link UsjClosingAttributeMarkerLocation}.
+ *
+ * A closing attribute marker location points to a specific point in the closing marker
+ * representation of an attribute marker (e.g., `\ca*` in USFM).
+ *
+ * @param location - The location to check.
+ * @returns `true` if the location is a `UsjClosingAttributeMarkerLocation`, `false` otherwise.
+ *
+ * @public
+ */
+export function isUsjClosingAttributeMarkerLocation(
+  location: UsjDocumentLocation | undefined | null,
+): location is UsjClosingAttributeMarkerLocation {
+  return (
+    location != null &&
+    "jsonPath" in location &&
+    "keyName" in location &&
+    "keyClosingMarkerOffset" in location
+  );
+}
+
+/**
+ * Gets a human-readable name for the type of a {@link UsjDocumentLocation}.
+ *
+ * Useful for error messages when an unsupported location type is encountered.
+ *
+ * @param location - The location to get the type name for.
+ * @returns A string describing the location type, or "undefined" / "null" if the location is not
+ *   provided.
+ *
+ * @public
+ */
+export function getUsjDocumentLocationTypeName(
+  location: UsjDocumentLocation | undefined | null,
+): string {
+  if (location === undefined) return "undefined";
+  if (location === null) return "null";
+  if (isUsjClosingAttributeMarkerLocation(location)) return "UsjClosingAttributeMarkerLocation";
+  if (isUsjAttributeKeyLocation(location)) return "UsjAttributeKeyLocation";
+  if (isUsjAttributeMarkerLocation(location)) return "UsjAttributeMarkerLocation";
+  if (isUsjPropertyValueLocation(location)) return "UsjPropertyValueLocation";
+  if (isUsjClosingMarkerLocation(location)) return "UsjClosingMarkerLocation";
+  if (isUsjTextContentLocation(location)) return "UsjTextContentLocation";
+  if (isUsjMarkerLocation(location)) return "UsjMarkerLocation";
+  return "Unknown";
+}

package/src/index.ts

@@ -3,9 +3,25 @@
  * Utilities for Scripture data conversion and manipulation, including USJ/USX format conversion.
  */
 
+export type * from "./converters/usj/usj-document-location.model.js";
 export type { Usj, BookCode, MarkerContent, MarkerObject } from "./converters/usj/usj.model.js";
 
 export { assertSafeKey } from "./converters/usj/converter.utils.js";
+export {
+  indexesFromUsjJsonPath,
+  usjJsonPathFromIndexes,
+} from "./converters/usj/jsonpath-indexes.js";
+export {
+  getUsjDocumentLocationTypeName,
+  isUsjAttributeKeyLocation,
+  isUsjAttributeMarkerLocation,
+  isUsjClosingAttributeMarkerLocation,
+  isUsjClosingMarkerLocation,
+  isUsjMarkerLocation,
+  isUsjPropertyValueLocation,
+  isUsjTextContentLocation,
+} from "./converters/usj/usj-document-location.utils.js";
+export { usjToUsxString } from "./converters/usj/usj-to-usx.js";
 export {
   EMPTY_USJ,
   MARKER_OBJECT_PROPS,
@@ -14,10 +30,5 @@ export {
   isValidBookCode,
   VALID_BOOK_CODES,
 } from "./converters/usj/usj.model.js";
-export { EMPTY_USX, USX_TYPE, USX_VERSION } from "./converters/usj/usx.model.js";
 export { usxStringToUsj } from "./converters/usj/usx-to-usj.js";
-export { usjToUsxString } from "./converters/usj/usj-to-usx.js";
-export {
-  indexesFromUsjJsonPath,
-  usjJsonPathFromIndexes,
-} from "./converters/usj/jsonpath-indexes.js";
+export { EMPTY_USX, USX_TYPE, USX_VERSION } from "./converters/usj/usx.model.js";