feat: lines

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

Author: unicornware

README.md

@@ -21,8 +21,11 @@ Wrap a string
 - [Install](#install)
 - [Use](#use)
 - [API](#api)
+  - [`lines(thing, config[, options])`](#linesthing-config-options)
 - [Types](#types)
   - [`Config`](#config)
+  - [`LinePadding`](#linepadding)
+  - [`LinesInfo`](#linesinfo)
   - [`Options`](#options)
   - [`ToString<[T]>`](#tostringt)
 - [Contribute](#contribute)
@@ -80,7 +83,27 @@ bun add @flex-development/string-wrap
 
 ## API
 
-**TODO**: api
+### `lines(thing, config[, options])`
+
+Get info about the lines of a wrapped string.
+
+#### Overloads
+
+- `lines(thing: unknown, config: number | string, options?: Options | null | undefined): LinesInfo`
+- `lines(thing: unknown, config: Config | number | string): LinesInfo`
+
+##### Parameters
+
+- `thing` (`unknown`)
+  — the thing to wrap. non-string values will be converted to strings
+- `config` ([`Config`](#config) | `number` | `string`)
+  — the wrap configuration or the number of columns to wrap the string to
+- `options` ([`Options`](#options) | `null` | `undefined`, `optional`)
+  — options for wrapping
+
+##### Returns
+
+([`LinesInfo`](#linesinfo)) Info about the lines forming the wrapped string
 
 ## Types
 
@@ -99,12 +122,38 @@ String wrapping configuration (`interface`).
 - `columns` (`number` | `string`)
   — the number of columns to wrap the string to
 
+### `LinePadding`
+
+The strings used to pad either side of each line (`type`).
+
+```ts
+type LinePadding = [left: string, right: string]
+```
+
+### `LinesInfo`
+
+Info about the lines of a wrapped string (`interface`).
+
+#### Properties
+
+- `eol` (`string`)
+  — the character, or characters, used to mark the end of a line
+- `indent` (`string`)
+  — the string used to indent each line
+- `lines` (`readonly string[]`)
+  — the list of lines forming the wrapped string
+- `padding` ([`LinePadding`](#linepadding))
+  — the strings used to pad either side of each line
+
 ### `Options`
 
 Options for wrapping a string (`interface`).
 
 #### Properties
 
+- `eol?` (`string` | `null` | `undefined`, optional)
+  — the character, or characters, used to mark the end of a line
+  - default: `'\n'`
 - `fill?` (`boolean` | `null` | `undefined`, optional)
   — whether to completely fill each column, splitting words as necessary.\
   by default, splits are made at spaces, ensuring that words aren't broken

package.json

@@ -60,6 +60,10 @@
       "string-wrap": "./src/internal/*.mts",
       "default": "./dist/internal/*.mjs"
     },
+    "#lib/*": {
+      "string-wrap": "./src/lib/*.mts",
+      "default": "./dist/lib/*.mjs"
+    },
     "#tests/*": "./__tests__/*.mts",
     "#types/*": {
       "string-wrap": "./src/types/*.mts",

src/__snapshots__/happy-dom/index.e2e.snap

@@ -1,3 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`e2e:string-wrap > should expose public api 1`] = `[]`;
+exports[`e2e:string-wrap > should expose public api 1`] = `
+[
+  "lines",
+]
+`;

src/__snapshots__/node/index.e2e.snap

@@ -1,3 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`e2e:string-wrap > should expose public api 1`] = `[]`;
+exports[`e2e:string-wrap > should expose public api 1`] = `
+[
+  "lines",
+]
+`;

src/index.mts

@@ -4,4 +4,5 @@
  */
 
 export type * from '#interfaces/index'
+export * from '#lib/index'
 export type * from '#types/index'

src/interfaces/__tests__/lines-info.spec-d.mts

@@ -0,0 +1,29 @@
+/**
+ * @file Type Tests - LinesInfo
+ * @module string-wrap/interfaces/tests/unit-d/LinesInfo
+ */
+
+import type TestSubject from '#interfaces/lines-info'
+import type { LinePadding } from '@flex-development/string-wrap'
+
+describe('unit-d:interfaces/LinesInfo', () => {
+  it('should match [eol: string]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('eol').toEqualTypeOf<string>()
+  })
+
+  it('should match [indent: string]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('indent').toEqualTypeOf<string>()
+  })
+
+  it('should match [lines: readonly string[]]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('lines')
+      .toEqualTypeOf<readonly string[]>()
+  })
+
+  it('should match [padding: LinePadding]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('padding')
+      .toEqualTypeOf<LinePadding>()
+  })
+})

src/interfaces/__tests__/options.spec-d.mts

@@ -12,6 +12,12 @@ describe('unit-d:interfaces/Options', () => {
     expectTypeOf<OptionalKeys<TestSubject>>().toEqualTypeOf<keyof TestSubject>()
   })
 
+  it('should match [eol?: string | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('eol')
+      .toEqualTypeOf<Nilable<string>>()
+  })
+
   it('should match [fill?: boolean | null | undefined]', () => {
     expectTypeOf<TestSubject>()
       .toHaveProperty('fill')

src/interfaces/index.mts

@@ -4,4 +4,5 @@
  */
 
 export type { default as Config } from '#interfaces/config'
+export type { default as LinesInfo } from '#interfaces/lines-info'
 export type { default as Options } from '#interfaces/options'

src/interfaces/lines-info.mts

@@ -0,0 +1,35 @@
+/**
+ * @file Interfaces - LinesInfo
+ * @module string-wrap/interfaces/LinesInfo
+ */
+
+import type { LinePadding } from '@flex-development/string-wrap'
+
+/**
+ * Info about the lines of a wrapped string.
+ */
+interface LinesInfo {
+  /**
+   * The character, or characters, used to mark the end of a line.
+   */
+  eol: string
+
+  /**
+   * The string used to indent each line.
+   */
+  indent: string
+
+  /**
+   * The list of lines forming the wrapped string.
+   */
+  lines: readonly string[]
+
+  /**
+   * The strings used to pad either side of each line.
+   *
+   * @see {@linkcode LinePadding}
+   */
+  padding: LinePadding
+}
+
+export type { LinesInfo as default }

src/interfaces/options.mts

@@ -9,6 +9,13 @@ import type { ToString } from '@flex-development/string-wrap'
  * Options for wrapping a string.
  */
 interface Options {
+  /**
+   * The character, or characters, used to mark the end of a line.
+   *
+   * @default '\n'
+   */
+  eol?: string | null | undefined
+
   /**
    * Whether to completely fill each column, splitting words as necessary.
    *