feat: wrap

unicornware · unicornware · commit e96917cd85b7 · 2025-11-29T21:22:37.000-05:00
Signed-off-by: Lexus Drumgold &lt;unicornware@flexdevelopment.llc&gt;
diff --git a/.dictionary.txt b/.dictionary.txt
@@ -1,5 +1,6 @@
 attw
 cefc
+commandoptst
 commitlintrc
 dedupe
 devlop
diff --git a/README.md b/README.md
@@ -22,6 +22,7 @@ Wrap a string
 - [Use](#use)
 - [API](#api)
   - [`lines(thing, config[, options])`](#linesthing-config-options)
+  - [`wrap(thing, config[, options])`](#wrapthing-config-options)
 - [Types](#types)
   - [`Config`](#config)
   - [`LinePadding`](#linepadding)
@@ -83,6 +84,13 @@ bun add @flex-development/string-wrap
 
 ## API
 
+This package exports the following identifiers:
+
+- [`lines`](#linesthing-config-options)
+- [`wrap`](#wrapthing-config-options)
+
+The default export is [`wrap`](#wrapthing-config-options).
+
 ### `lines(thing, config[, options])`
 
 Get info about the lines of a wrapped string.
@@ -105,6 +113,28 @@ Get info about the lines of a wrapped string.
 
 ([`LinesInfo`](#linesinfo)) Info about the lines forming the wrapped string
 
+### `wrap(thing, config[, options])`
+
+Wrap a string to the specified column width.
+
+#### Overloads
+
+- `wrap(thing: unknown, config: number | string, options?: Options | null | undefined): string`
+- `wrap(thing: unknown, config: Config | number | string): string`
+
+##### 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
+
+(`string`) The wrapped string
+
 ## Types
 
 This package is fully typed with [TypeScript][].
diff --git a/__fixtures__/parsed-options.mts b/__fixtures__/parsed-options.mts
@@ -0,0 +1,11 @@
+/**
+ * @file Fixtures - parsedOptions
+ * @module fixtures/parsedOptions
+ */
+
+/**
+ * A long string containing several sequences and a line break.
+ *
+ * @type {string}
+ */
+export default 'Parsed options can be accessed by calling [`.opts<T>()`](#commandoptst) on a [`Command`](#commandinfo) object, and are passed to the command\'s [`action`](#commandactionaction) handler.\nMulti-word options such as `--template-engine` are `camelCased`, becoming `program.opts().templateEngine`, or can be configured to be converted using `snake_case`, becoming `program.opts().template_engine`.'
diff --git a/src/__snapshots__/happy-dom/index.e2e.snap b/src/__snapshots__/happy-dom/index.e2e.snap
@@ -3,5 +3,6 @@
 exports[`e2e:string-wrap > should expose public api 1`] = `
 [
   "lines",
+  "wrap",
 ]
 `;
diff --git a/src/__snapshots__/node/index.e2e.snap b/src/__snapshots__/node/index.e2e.snap
@@ -3,5 +3,6 @@
 exports[`e2e:string-wrap > should expose public api 1`] = `
 [
   "lines",
+  "wrap",
 ]
 `;
diff --git a/src/lib/__snapshots__/happy-dom/index.e2e.snap b/src/lib/__snapshots__/happy-dom/index.e2e.snap
@@ -3,5 +3,6 @@
 exports[`e2e:lib > should expose public api 1`] = `
 [
   "lines",
+  "wrap",
 ]
 `;
diff --git a/src/lib/__snapshots__/happy-dom/wrap.snap b/src/lib/__snapshots__/happy-dom/wrap.snap
@@ -0,0 +1,10 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`unit:lib/wrap > should return wrapped string 1`] = `
+"Parsed options can be accessed by calling [\`.opts<T>()\`](#commandoptst)
+on a [\`Command\`](#commandinfo) object, and are passed to the command's
+[\`action\`](#commandactionaction) handler.
+Multi-word options such as \`--template-engine\` are \`camelCased\`,
+becoming \`program.opts().templateEngine\`, or can be configured to be
+converted using \`snake_case\`, becoming \`program.opts().template_engine\`."
+`;
diff --git a/src/lib/__snapshots__/node/index.e2e.snap b/src/lib/__snapshots__/node/index.e2e.snap
@@ -3,5 +3,6 @@
 exports[`e2e:lib > should expose public api 1`] = `
 [
   "lines",
+  "wrap",
 ]
 `;
diff --git a/src/lib/__snapshots__/node/wrap.snap b/src/lib/__snapshots__/node/wrap.snap
@@ -0,0 +1,10 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`unit:lib/wrap > should return wrapped string 1`] = `
+"Parsed options can be accessed by calling [\`.opts<T>()\`](#commandoptst)
+on a [\`Command\`](#commandinfo) object, and are passed to the command's
+[\`action\`](#commandactionaction) handler.
+Multi-word options such as \`--template-engine\` are \`camelCased\`,
+becoming \`program.opts().templateEngine\`, or can be configured to be
+converted using \`snake_case\`, becoming \`program.opts().template_engine\`."
+`;
diff --git a/src/lib/__tests__/wrap.spec.mts b/src/lib/__tests__/wrap.spec.mts
@@ -0,0 +1,18 @@
+/**
+ * @file Unit Tests - wrap
+ * @module string-wrap/lib/tests/unit/wrap
+ */
+
+import parsedOptions from '#fixtures/parsed-options'
+import testSubject from '#lib/wrap'
+
+describe('unit:lib/wrap', () => {
+  it('should return wrapped string', () => {
+    // Act
+    const result = testSubject(parsedOptions, { columns: 72, hard: true })
+
+    // Expect
+    expect(result).to.be.a('string').and.not.empty
+    expect(result).toMatchSnapshot()
+  })
+})
diff --git a/src/lib/index.mts b/src/lib/index.mts
@@ -4,3 +4,4 @@
  */
 
 export { default as lines } from '#lib/lines'
+export { default as wrap } from '#lib/wrap'
diff --git a/src/lib/wrap.mts b/src/lib/wrap.mts
@@ -0,0 +1,79 @@
+/**
+ * @file wrap
+ * @module string-wrap/lib/wrap
+ */
+
+import lines from '#lib/lines'
+import type { Config, Options } from '@flex-development/string-wrap'
+
+export default wrap
+
+/**
+ * Wrap a string to the specified number of `columns`.
+ *
+ * @see {@linkcode Options}
+ *
+ * @this {void}
+ *
+ * @param {unknown} thing
+ *  The thing to wrap. Non-string values will be converted to strings
+ * @param {number | string} columns
+ *  The number of columns to wrap the string to
+ * @param {Options | null | undefined} [options]
+ *  Options for wrapping
+ * @return {string}
+ *  The wrapped string
+ */
+function wrap(
+  this: void,
+  thing: unknown,
+  columns: number | string,
+  options?: Options | null | undefined
+): string
+
+/**
+ * Wrap a string to the specified column width.
+ *
+ * @see {@linkcode Config}
+ *
+ * @this {void}
+ *
+ * @param {unknown} thing
+ *  The thing to wrap. Non-string values will be converted to strings
+ * @param {Config | number | string} config
+ *  The wrap configuration or the number of columns to wrap the string to
+ * @return {string}
+ *  The wrapped string
+ */
+function wrap(
+  this: void,
+  thing: unknown,
+  config: Config | number | string
+): string
+
+/**
+ * Wrap a string to the specified column width.
+ *
+ * @see {@linkcode Config}
+ * @see {@linkcode Options}
+ *
+ * @this {void}
+ *
+ * @param {unknown} thing
+ *  The thing to wrap. Non-string values will be converted to strings
+ * @param {Config | number | string} config
+ *  The wrap configuration or the number of columns to wrap the string to
+ * @param {Options | null | undefined} [options]
+ *  Options for wrapping
+ * @return {string}
+ *  The wrapped string
+ */
+function wrap(
+  this: void,
+  thing: unknown,
+  config: Config | number | string,
+  options?: Options | null | undefined
+): string {
+  const { eol, lines: list } = lines(thing, config as never, options)
+  return list.join(eol)
+}

-Original file line number
+Diff line change
@@ @@ -1,5 +1,6 @@ @@
 attw
 cefc
 +commandoptst
 commitlintrc
 dedupe
 devlop
Original file line number	Diff line number	Diff line change
`@@ -3,5 +3,6 @@`
`3`	`3`	exports[`e2e:string-wrap > should expose public api 1`] = `
`4`	`4`	`[`
`5`	`5`	`"lines",`
	`6`	`+ "wrap",`
`6`	`7`	`]`
`7`	`8`	`;
Original file line number	Diff line number	Diff line change
`@@ -3,5 +3,6 @@`
`3`	`3`	exports[`e2e:lib > should expose public api 1`] = `
`4`	`4`	`[`
`5`	`5`	`"lines",`
	`6`	`+ "wrap",`
`6`	`7`	`]`
`7`	`8`	`;