@wollybeard/kit

Appearance

Str.Tpl ​

Str / Tpl

Import ​

typescript
import { Str } from '@wollybeard/kit'

// Access via namespace
Str.Tpl.someFunction()
typescript
import * as Str from '@wollybeard/kit/str'

// Access via namespace
Str.Tpl.someFunction()

Template ​

[T] Tpl ​

typescript
type Tpl = TemplateStringsArray
Source

Convenience re-export of the built-in TemplateStringsArray type. Contains the string parts of a tagged template literal along with a raw property.

Examples:

typescript
function 
tag
(
strings
: 
Str
.Tpl.Tpl.
Array
, ...
values
: unknown[]) {
  // strings is TemplateStringsArray
  // strings[0] = "Hello "
  // strings[1] = "!"
  // strings.raw contains raw string values
}

tag
`Hello ${
name
}!`

[F] is ​

typescript
(value: unknown): boolean
Source

Parameters:

  • value - Value to check

Returns: True if value is a TemplateStringsArray

Type guard to check if a value is a TemplateStringsArray. Used to detect when a function is called as a tagged template literal.

Examples:

typescript
function 
tag
(...
args
: unknown[]) {
  if (isArray(
args
[0])) {
    // Called as tag`template`
  } else {
    // Called as tag()
  }
}

[T] CallInput ​

typescript
type CallInput = [Tpl, ...unknown[]]
Source

Tagged template literal arguments tuple. First element is the template strings array, followed by interpolated values.

Examples:

typescript
function 
tag
(...
args
: unknown[]) {
  if (isArgs(
args
)) {
    const [
strings
, ...
values
] = 
args

    // Process template literal
  }
}

tag
`Hello ${
name
}!`

[F] isCallInput ​

typescript
(value: unknown): boolean
Source

Parameters:

  • value - Function arguments to check

Returns: True if args are tagged template literal arguments

Type guard to check if function arguments are from a tagged template literal.

Examples:

typescript
function 
tag
(...
args
: unknown[]) {
  if (isArgs(
args
)) {
    const [
strings
, ...
values
] = 
args

    // Process as template literal
  }
}

tag
`Hello ${
name
}!`

[F] normalizeCall ​

typescript
(callInput: CallInput): Call
Source

Parameters:

  • callInput - Tagged template literal arguments

Returns: Object with parts (TemplateStringsArray) and values (unknown[])

Parse tagged template literal arguments into structured parts and values.

Examples:

typescript
function 
tag
(...
args
: unknown[]) {
  if (isArgs(
args
)) {
    const { 
parts
, 
values
 } = parse(
args
)
    // parts[0] = "Hello "
    // parts[1] = "!"
    // values[0] = name
  }
}

tag
`Hello ${
name
}!`

[F] renderWith ​

typescript
(mapper: (value: unknown) => string): (callInput: CallInput) => string
Source

Parameters:

  • mapper - Function to convert interpolated values to strings

Returns: Function that takes template args and returns rendered string

Render tagged template literal arguments using a custom value renderer.

Examples:

typescript
// Custom renderer for JSON values
const 
renderJson
 = 
Str
.Tpl.renderWith(
v
 => 
JSON
.
stringify
(
v
))
function 
tag
(...
args
: unknown[]) {
  if (isArgs(
args
)) return 
renderJson
(
args
)
}

tag
`Value: ${{ 
foo
: 'bar' }}` // "Value: {\"foo\":\"bar\"}"

// Custom renderer that prefixes values
const 
renderPrefixed
 = 
Str
.Tpl.renderWith(
v
 => `[${
v
}]`)

[C] render ​

typescript
;((callInput: CallInput) => string)
Source

Render tagged template literal arguments to a string. Interpolated values are converted using plain String() coercion.

Examples:

typescript
function 
tag
(...
args
: unknown[]) {
  if (isArgs(
args
)) {
    return 
Str
.Tpl.render(
args
)
  }
}

tag
`Hello ${
name
}!` // "Hello World!"

tag
`Count: ${42}` // "Count: 42"

[F] passthrough ​

typescript
(strings: TemplateStringsArray, ...values?: unknown[]): string
Source

Parameters:

  • strings - Template string parts
  • values - Interpolated values

Returns: The composed string with values interpolated

A passthrough tagged template literal that returns the interpolated string as-is. Useful for semantic clarity in code without any processing.

Examples:

typescript
const 
template
 = passthrough
const 
message
 = 
template
`Hello ${
name
}, you have ${count} items.`
// Result: "Hello Alice, you have 5 items."

[F] dedent ​

typescript
(strings: TemplateStringsArray, ...values?: unknown[]): string
Source

Parameters:

  • strings - Template string parts (uses raw strings to preserve escapes)
  • values - Interpolated values

Returns: Dedented string with common indentation removed

Tagged template literal that removes common indentation from all lines. Automatically indents multi-line interpolated values to match their context.

Uses the raw template strings to preserve escape sequences (e.g., \n stays as backslash-n). Trims leading and trailing blank lines from the result.

Examples:

typescript
const 
code
 = dedent`
  function greet() {
    console.log('Hello')
  }
`
// Result: "function greet() {\n  console.log('Hello')\n}"
typescript
// Multi-line values are auto-indented
const 
inner
 = 'line1\nline2'
const 
code
 = dedent`
  outer:
    ${
inner
}
`
// Result: "outer:\n  line1\n  line2"
typescript
// Escape sequences are preserved
const 
path
 = dedent`
  C:\Users\name\Documents
`
// Result: "C:\\Users\\name\\Documents" (backslashes preserved)

[T] HighlightTag ​

typescript
type HighlightTag = typeof passthrough
Source

Type for a tagged template literal function used for syntax highlighting.

[C] highlight ​

typescript
{
  ts: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
  js: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
  html: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
  css: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
  sql: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
  json: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
  yaml: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
  yml: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
  graphql: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
  gql: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
  iso: ;
  ;((strings: TemplateStringsArray, ...values: unknown[]) => string)
}
Source

Object containing language-specific template tag functions for syntax highlighting. Each property is a tagged template function that provides editor syntax highlighting for that language (when supported by the editor).

Automatically dedents content

  • Removes common indentation and trims blank lines, allowing you to write naturally indented template literals in your source code while producing clean output. Relative indentation is preserved.

Implemented as a Proxy that returns the same dedent function for all properties, allowing destructuring and property access to work seamlessly.

Supported languages are based on common supported editor injection patterns:

Examples:

typescript
import { 
Str
 } from '@wollybeard/kit'

const { 
ts
, 
html
, 
sql
 } = 
Str
.Tpl.highlight

// Source indentation is automatically removed
const 
code
 = 
ts
`
  export const add = (a: number, b: number) => {
    return a + b
  }
`
// Result: "export const add = (a: number, b: number) => {\n  return a + b\n}"
// ^ Clean output with relative indentation preserved

const 
markup
 = 
html
`
  <div class="container">
    <h1>Title</h1>
  </div>
` // Gets HTML syntax highlighting, auto-dedented

const 
query
 = 
sql
`
  SELECT * FROM users
  WHERE id = ${userId}
` // Gets SQL syntax highlighting, auto-dedented

Other ​

[I] Call ​

typescript
interface Call {
  template: Tpl
  args: unknown[]
}
Source