feat: stringifyPosition

Signed-off-by: Lexus Drumgold <[email protected]>

.codecov.yml

@@ -89,4 +89,5 @@ ignore:
   - '!src/index.ts'
 
 profiling:
-  critical_files_paths: []
+  critical_files_paths:
+    - src/stringify-position.ts

.github/infrastructure.yml

@@ -168,7 +168,7 @@ repository:
   automated_security_fixes: true
   default_branch: main
   delete_branch_on_merge: true
-  description: unist utility to serialize a node, position, point, or range
+  description: unist utility to serialize the positional info of a node, point, position, or range
   has_issues: true
   has_projects: true
   has_wiki: false

README.md

@@ -2,15 +2,15 @@
 
 [![github release](https://img.shields.io/github/v/release/flex-development/unist-util-stringify-position.svg?include_prereleases&sort=semver)](https://github.com/flex-development/unist-util-stringify-position/releases/latest)
 [![npm](https://img.shields.io/npm/v/@flex-development/unist-util-stringify-position.svg)](https://npmjs.com/package/@flex-development/unist-util-stringify-position)
-[![codecov](https://codecov.io/gh/flex-development/unist-util-stringify-position/graph/badge.svg?token=SXBHbtdEko)](https://codecov.io/gh/flex-development/unist-util-stringify-position)
+[![codecov](https://codecov.io/gh/flex-development/unist-util-stringify-position/graph/badge.svg?token=oB6Ip38ZJt)](https://codecov.io/gh/flex-development/unist-util-stringify-position)
 [![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)
 [![license](https://img.shields.io/github/license/flex-development/unist-util-stringify-position.svg)](LICENSE.md)
 [![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits&logoColor=ffffff)](https://conventionalcommits.org/)
 [![typescript](https://img.shields.io/badge/-typescript-3178c6?logo=typescript&logoColor=ffffff)](https://typescriptlang.org/)
 [![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat&logo=vitest&logoColor=ffffff)](https://vitest.dev/)
 [![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat&logo=yarn&logoColor=ffffff)](https://yarnpkg.com/)
 
-[unist][unist] utility to pretty print positional info
+[unist][unist] utility to serialize the positional info of a node, point, position, or range
 
 ## Contents
 
@@ -19,17 +19,28 @@
 - [Install](#install)
 - [Use](#use)
 - [API](#api)
+  - [`stringifyPosition([info][, options])`](#stringifypositioninfo-options)
 - [Types](#types)
+  - [`Info`](#info)
+  - [`LiteralLike`](#literallike)
+  - [`NodeLike`](#nodelike)
+  - [`Options`](#options)
+  - [`ParentLike`](#parentlike)
+  - [`PointLike`](#pointlike)
+  - [`PositionLike`](#positionlike)
+  - [`Range`](#range)
 - [Related](#related)
 - [Contribute](#contribute)
 
 ## What is this?
 
-**TODO**: what is this?
+This is a tiny, but useful, package that takes any [unist][unist] node, point, position, or range and serializes its
+positional info.
 
 ## When should I use this?
 
-**TODO**: when should I use this?
+Use this package when you want a standard format for serialized positional info, such as when inspecting trees, or
+throwing errors.
 
 ## Install
 
@@ -64,24 +75,151 @@ In browsers with [`esm.sh`][esmsh]:
 
 ## Use
 
-**TODO**: use
+```ts
+import { u } from '@flex-development/unist-util-builder'
+import {
+  stringifyPosition,
+  type LiteralLike,
+  type PointLike,
+  type PositionLike,
+  type Range
+} from '@flex-development/unist-util-stringify-position'
+
+const node: LiteralLike = u('text', {
+  position: {
+    end: { column: 13, line: 1, offset: 12 },
+    start: { column: 1, line: 1, offset: 0 }
+  },
+  value: 'hello world!'
+})
+
+const point: PointLike = { column: 9, line: 6 }
+
+const position: PositionLike = { end: { line: 8 }, start: { line: 7 } }
+
+const range: Range = [{ column: 2, line: 3 }, { column: 2, line: 5 }]
+
+console.log('node:', stringifyPosition(node, { offsets: true }))
+console.log('point:', stringifyPosition(point))
+console.log('position:', stringifyPosition(position))
+console.log('range:', stringifyPosition(range))
+```
+
+...yields
+
+```sh
+node: 1:1-1:13, 0-12
+point: 6:9
+position: 7:1-8:1
+range: 3:2-5:2
+```
 
 ## API
 
-**TODO**: api
+This package exports the identifier [`stringifyPosition`](#stringifypositioninfo-options).
+
+There is no default export.
+
+### `stringifyPosition([info][, options])`
+
+Serialize the positional info of a node, point, position, or range.
+
+The serialized info is returned in one the following formats:
+
+- `ls:cs-le:ce, os-oe` (node, position, range)
+- `ls:cs-le:ce` (node, position, range)
+- `l:c` (point)
+
+where `l` stands for line, `c` for column, `o` for offset, `s` for `start`, and `e` for end.
+
+An empty string (`''`) is returned if the given info is neither node, point, position, nor range.
+
+#### Parameters
+
+- `info` ([`Info`](#info) | `null` | `undefined`) — node, point, position, or range
+- `options` ([`Options`](#options) | `null` | `undefined`) — configuration options
+  - `options.offsets` (`boolean | null | undefined`) — serialize offsets if `info` is a node, position, or range
+
+#### Returns
+
+(`string`) Pretty printed positional info.
 
 ## Types
 
 This package is fully typed with [TypeScript][typescript].
 
+### `Info`
+
+Union of positional info objects (TypeScript type).
+
+```ts
+type Info =
+  | Literal
+  | LiteralLike
+  | Node
+  | NodeLike
+  | Parent
+  | ParentLike
+  | Point
+  | PointLike
+  | Position
+  | PositionLike
+  | Range
+```
+
+### `LiteralLike`
+
+Loose [literal][literal] (TypeScript type).
+
+### `NodeLike`
+
+Loose [node][node] (TypeScript type).
+
+### `Options`
+
+Configuration options (TypeScript type).
+
+```ts
+type Options = {
+  offsets?: boolean | null | undefined
+}
+```
+
+#### Fields
+
+- `offsets` (`boolean | null | undefined`) — serialize offsets if positional info is a node, position, or range
+
+### `ParentLike`
+
+Loose [parent][parent] (TypeScript type).
+
+### `PointLike`
+
+Loose [point][point] (TypeScript type).
+
+### `PositionLike`
+
+Loose [position][position] (TypeScript type).
+
+### `Range`
+
+List, where the first value is the place of the first character in a source region, and the last is the place of the
+last character in the region. (TypeScript type).
+
+```ts
+type Range = [
+  start?: Point | PointLike | null | undefined,
+  end?: Point | PointLike | null | undefined
+]
+```
+
 ## Related
 
-- [`unist-util-generated`][unist-util-generated] — [unist][unist] utility to check if a node is generated
-- [`unist-util-position`][unist-util-position] — [unist][unist] utility to get positional info of nodes
-- [`unist-util-remove-position`][unist-util-remove-position] — [unist][unist] utility to remove positional info
-- [`unist-util-source`][unist-util-source] — [unist][unist] utility to get the source of a value (node or
-  position) in a file
-- [`unist-util-types`][unist-util-types] — [unist][unist] utility types
+- [`unist-util-generated`][unist-util-generated] — check if a node is generated
+- [`unist-util-position`][unist-util-position] — get positional info of nodes
+- [`unist-util-remove-position`][unist-util-remove-position] — remove positional info from trees
+- [`unist-util-source`][unist-util-source] — get the source of a value (node or position) in a file
+- [`unist-util-types`][unist-util-types] — utility types
 
 ## Contribute
 
@@ -90,13 +228,18 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md).
 This project has a [code of conduct](CODE_OF_CONDUCT.md). By interacting with this repository, organization, or
 community you agree to abide by its terms.
 
-[yarn]: https://yarnpkg.com
-[unist]: https://github.com/syntax-tree/unist
-[unist-util-types]: https://github.com/flex-development/unist-util-types
-[unist-util-source]: https://github.com/syntax-tree/unist-util-source
-[unist-util-remove-position]: https://github.com/syntax-tree/unist-util-remove-position
-[unist-util-position]: https://github.com/syntax-tree/unist-util-position
-[unist-util-generated]: https://github.com/syntax-tree/unist-util-generated
-[typescript]: https://www.typescriptlang.org
-[esmsh]: https://esm.sh/
 [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+[esmsh]: https://esm.sh/
+[literal]: https://github.com/syntax-tree/unist#literal
+[node]: https://github.com/syntax-tree/unist#node
+[parent]: https://github.com/syntax-tree/unist#parent
+[point]: https://github.com/syntax-tree/unist#point
+[position]: https://github.com/syntax-tree/unist#position
+[typescript]: https://www.typescriptlang.org
+[unist-util-generated]: https://github.com/syntax-tree/unist-util-generated
+[unist-util-position]: https://github.com/syntax-tree/unist-util-position
+[unist-util-remove-position]: https://github.com/syntax-tree/unist-util-remove-position
+[unist-util-source]: https://github.com/syntax-tree/unist-util-source
+[unist-util-types]: https://github.com/flex-development/unist-util-types
+[unist]: https://github.com/syntax-tree/unist
+[yarn]: https://yarnpkg.com

__tests__/setup/faker.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Test Setup - faker
+ * @module tests/setup/faker
+ * @see https://github.com/faker-js/faker
+ */
+
+import { faker } from '@faker-js/faker'
+
+global.faker = faker

__tests__/setup/index.ts

@@ -3,4 +3,4 @@
  * @module tests/setup
  */
 
-export {}
+import './faker'

eslint.config.mjs

@@ -21,5 +21,11 @@ export default [
       '**/dist/',
       '__fixtures__/underscore-1.5.2.js'
     ]
+  },
+  {
+    files: ['src/stringify-position.ts'],
+    rules: {
+      '@typescript-eslint/unified-signatures': 0
+    }
   }
 ]

package.json

@@ -81,6 +81,7 @@
     "@commitlint/cli": "19.3.0",
     "@commitlint/types": "19.0.3",
     "@eslint/js": "9.6.0",
+    "@faker-js/faker": "9.0.0-alpha.1",
     "@flex-development/commitlint-config": "1.0.1",
     "@flex-development/decorator-regex": "2.0.0",
     "@flex-development/esm-types": "2.0.0",
@@ -89,6 +90,7 @@
     "@flex-development/mlly": "1.0.0-alpha.18",
     "@flex-development/pathe": "2.0.0",
     "@flex-development/tutils": "6.0.0-alpha.25",
+    "@flex-development/unist-util-builder": "1.0.0",
     "@stylistic/eslint-plugin": "2.3.0",
     "@types/chai": "4.3.16",
     "@types/eslint": "8.56.10",

src/__snapshots__/stringify-position.functional.snap

@@ -0,0 +1,39 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`functional:stringifyPosition > node > should serialize node (invalid position #1) 1`] = `"1:1-1:1"`;
+
+exports[`functional:stringifyPosition > node > should serialize node (invalid position #2) 1`] = `"1:1-1:1"`;
+
+exports[`functional:stringifyPosition > node > should serialize node (invalid position #3) 1`] = `"1:1-1:1"`;
+
+exports[`functional:stringifyPosition > node > should serialize node (no position) 1`] = `"1:1-1:1"`;
+
+exports[`functional:stringifyPosition > node > should serialize node (valid) 1`] = `"63:8-63:55"`;
+
+exports[`functional:stringifyPosition > node > should serialize node (valid, offsets) 1`] = `"114:76-115:1, 2606-2607"`;
+
+exports[`functional:stringifyPosition > point > should serialize point (column only) 1`] = `"1:3"`;
+
+exports[`functional:stringifyPosition > point > should serialize point (line only) 1`] = `"13:1"`;
+
+exports[`functional:stringifyPosition > point > should serialize point (no indices) 1`] = `"1:1"`;
+
+exports[`functional:stringifyPosition > point > should serialize point (valid) 1`] = `"2:3"`;
+
+exports[`functional:stringifyPosition > position > should serialize position (invalid points #1) 1`] = `"1:1-1:1"`;
+
+exports[`functional:stringifyPosition > position > should serialize position (invalid points #2) 1`] = `"1:1-1:1"`;
+
+exports[`functional:stringifyPosition > position > should serialize position (invalid points #3) 1`] = `"1:1-1:1"`;
+
+exports[`functional:stringifyPosition > position > should serialize position (no points) 1`] = `"1:1-1:1"`;
+
+exports[`functional:stringifyPosition > position > should serialize position (valid) 1`] = `"111:6-128:42"`;
+
+exports[`functional:stringifyPosition > position > should serialize position (valid, offsets) 1`] = `"1:1-4:4, 0-73"`;
+
+exports[`functional:stringifyPosition > range > should serialize range (no points) 1`] = `"1:1-1:1"`;
+
+exports[`functional:stringifyPosition > range > should serialize range (valid) 1`] = `"42:6-38:3"`;
+
+exports[`functional:stringifyPosition > range > should serialize range (valid, offsets) 1`] = `"13:4-13:51, 347-521"`;

src/__tests__/index.e2e.spec.ts

@@ -0,0 +1,12 @@
+/**
+ * @file E2E Tests - api
+ * @module unist-util-stringify-position/tests/e2e/api
+ */
+
+import * as testSubject from '../index'
+
+describe('e2e:unist-util-stringify-position', () => {
+  it('should expose public api', () => {
+    expect(testSubject).to.have.keys(['stringifyPosition'])
+  })
+})