# Core Delegates

Core delegates are shipped with WireBox and are always available via the `@coreDelegates` namespace — no ColdBox required.

{% hint style="success" %}
For a deep dive into how WireBox delegation works (annotations, prefixes, suffixes, targeted methods), see the [WireBox Delegators](https://wirebox.ortusbooks.com/usage/wirebox-delegators) documentation.
{% endhint %}

## Available Core Delegates

| WireBox ID                 | Class Path                                 | Description                                             |
| -------------------------- | ------------------------------------------ | ------------------------------------------------------- |
| `Async@coreDelegates`      | `coldbox.system.core.delegates.Async`      | Async/parallel programming via the ColdBox AsyncManager |
| `DateTime@coreDelegates`   | `coldbox.system.core.delegates.DateTime`   | Date and time utilities via DateTimeHelper              |
| `Env@coreDelegates`        | `coldbox.system.core.delegates.Env`        | Java system properties and OS environment variables     |
| `Flow@coreDelegates`       | `coldbox.system.core.delegates.Flow`       | Fluent flow-control methods for expressive chaining     |
| `JsonUtil@coreDelegates`   | `coldbox.system.core.delegates.JsonUtil`   | JSON serialization utilities                            |
| `Population@coreDelegates` | `coldbox.system.core.delegates.Population` | Object population from structs, JSON, XML, and queries  |
| `StringUtil@coreDelegates` | `coldbox.system.core.delegates.StringUtil` | String manipulation and formatting utilities            |

***

## Async

**WireBox ID:** `Async@coreDelegates`

Provides access to the ColdBox `AsyncManager`. Delegates `newFuture()` and `arrayRange()` directly; also exposes `async()` to retrieve the `AsyncManager` instance.

| Method            | Description                                    |
| ----------------- | ---------------------------------------------- |
| `async()`         | Returns the `AsyncManager` instance            |
| `newFuture(...)`  | Creates and returns a new `Future` object      |
| `arrayRange(...)` | Creates a ranged parallel stream from an array |

{% tabs %}
{% tab title="BoxLang" %}

```java
class delegates="Async@coreDelegates" {

    function process() {
        var result = newFuture( () => expensiveOperation() ).get()
        arrayRange( [1,2,3], ( item ) => processItem( item ) )
    }

}
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
component delegates="Async@coreDelegates" {

    function process() {
        var result = newFuture( function() { return expensiveOperation() } ).get()
        arrayRange( [1,2,3], function( item ) { return processItem( item ) } )
    }

}
```

{% endtab %}
{% endtabs %}

***

## DateTime

**WireBox ID:** `DateTime@coreDelegates`

Delegates **all** public methods from `coldbox.system.async.time.DateTimeHelper` directly onto your class.

{% tabs %}
{% tab title="BoxLang" %}

```java
class delegates="DateTime@coreDelegates" {

    function isExpired( required date expiresAt ) {
        return expiresAt.isBefore( now() )
    }

    function getNextWeek() {
        return now().plusDays( 7 )
    }

}
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
component delegates="DateTime@coreDelegates" {

    function isExpired( required date expiresAt ) {
        return expiresAt.isBefore( now() )
    }

    function getNextWeek() {
        return now().plusDays( 7 )
    }

}
```

{% endtab %}
{% endtabs %}

***

## Env

**WireBox ID:** `Env@coreDelegates`

Reads Java system properties and OS environment variables. Methods search Java properties first, then OS env vars, unless specified otherwise.

{% hint style="warning" %}
In ColdBox 8+, the old `getSystemSetting()`, `getSystemProperty()`, and `getEnv()` utility methods were **removed** from the framework supertype and replaced by this delegate.
{% endhint %}

| Method                                   | Description                                                                                                                            |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `getSystemSetting( key, defaultValue )`  | Returns value from **Java system properties first, then OS env vars**. Throws `SystemSettingNotFound` if missing and no default given. |
| `getSystemProperty( key, defaultValue )` | Returns a **Java system property** (`-Dkey=value`) only.                                                                               |
| `getEnv( key, defaultValue )`            | Returns an **OS environment variable** only.                                                                                           |
| `getJavaSystem()`                        | Returns the raw `java.lang.System` instance.                                                                                           |

{% tabs %}
{% tab title="BoxLang" %}

```java
class delegates="Env@coreDelegates" {

    function getDatabaseUrl() {
        return getSystemSetting( "DB_URL", "jdbc:h2:mem:testdb" )
    }

    function getPort() {
        // Required — throws SystemSettingNotFound if missing
        return getEnv( "SERVER_PORT" )
    }

}
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
component delegates="Env@coreDelegates" {

    function getDatabaseUrl() {
        return getSystemSetting( "DB_URL", "jdbc:h2:mem:testdb" )
    }

    function getPort() {
        // Required — throws SystemSettingNotFound if missing
        return getEnv( "SERVER_PORT" )
    }

}
```

{% endtab %}
{% endtabs %}

***

## Flow

**WireBox ID:** `Flow@coreDelegates`

Fluent flow-control methods. All methods return the parent object so calls can be chained.

| Method                                         | Description                                                                          |
| ---------------------------------------------- | ------------------------------------------------------------------------------------ |
| `peek( target )`                               | Executes a closure with the parent as its argument; returns the parent for chaining. |
| `when( target, success, failure )`             | Runs `success` if `target` is truthy; `failure` if falsy (optional).                 |
| `unless( target, success, failure )`           | Runs `success` if `target` is falsy; `failure` if truthy (optional).                 |
| `throwIf( target, type, message, detail )`     | Throws an exception if `target` is `true`.                                           |
| `throwUnless( target, type, message, detail )` | Throws an exception if `target` is `false`.                                          |
| `ifNull( target, success, failure )`           | Runs `success` if `target` is `null`; `failure` if not null (optional).              |
| `ifPresent( target, success, failure )`        | Runs `success` if `target` is **not** `null`; `failure` if null (optional).          |

{% tabs %}
{% tab title="BoxLang" %}

```java
class delegates="Flow@coreDelegates" {

    function save( required struct data ) {
        return this
            .throwIf( data.isEmpty(), "ValidationException", "Data cannot be empty" )
            .when( data.keyExists( "email" ), () => validateEmail( data.email ) )
            .peek( (self) => logBox.getRootLogger().info( "Saving #data.name#" ) )
    }

}
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
component delegates="Flow@coreDelegates" {

    function save( required struct data ) {
        return this
            .throwIf( data.isEmpty(), "ValidationException", "Data cannot be empty" )
            .when( data.keyExists( "email" ), function() { validateEmail( data.email ) } )
            .peek( function( self ) { logBox.getRootLogger().info( "Saving #data.name#" ) } )
    }

}
```

{% endtab %}
{% endtabs %}

***

## JsonUtil

**WireBox ID:** `JsonUtil@coreDelegates`

JSON serialization utilities. `toJson`, `prettyJson`, and `toPrettyJson` are delegated from the framework's core `Util` class.

| Method                 | Description                                                                         |
| ---------------------- | ----------------------------------------------------------------------------------- |
| `toJson( data )`       | Serializes any data to a JSON string.                                               |
| `prettyJson( data )`   | Serializes to an indented, human-readable JSON string.                              |
| `toPrettyJson( data )` | Alias for `prettyJson()`.                                                           |
| `forAttribute( data )` | Serializes to JSON (if complex) then encodes for safe use inside an HTML attribute. |

{% tabs %}
{% tab title="BoxLang" %}

```java
class delegates="JsonUtil@coreDelegates" {

    function toApiResponse( required struct data ) {
        return {
            raw       : toJson( data ),
            pretty    : prettyJson( data ),
            attribute : forAttribute( data )
        }
    }

}
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
component delegates="JsonUtil@coreDelegates" {

    function toApiResponse( required struct data ) {
        return {
            raw       : toJson( data ),
            pretty    : prettyJson( data ),
            attribute : forAttribute( data )
        }
    }

}
```

{% endtab %}
{% endtabs %}

***

## Population

**WireBox ID:** `Population@coreDelegates`

Populates object properties from structs, JSON strings, XML, or query rows using the WireBox Object Populator. The `target` argument defaults to `$parent` (the delegating object itself).

{% hint style="info" %}
If you need to populate an object **from the current HTTP request collection**, use [`Population@cbDelegates`](/digging-deeper/delegates/coldbox-delegates.md#population) instead — it automatically defaults `memento` to the request collection.
{% endhint %}

| Method                                       | Description                                |
| -------------------------------------------- | ------------------------------------------ |
| `populate( memento, ... )`                   | Populate from a struct/map.                |
| `populateWithPrefix( memento, prefix, ... )` | Populate using prefixed keys.              |
| `populateFromJSON( JSONString, ... )`        | Populate from a JSON string.               |
| `populateFromXML( xml, root, ... )`          | Populate from an XML string or XML object. |
| `populateFromQuery( qry, rowNumber, ... )`   | Populate from a specific query row.        |

{% tabs %}
{% tab title="BoxLang" %}

```java
class delegates="Population@coreDelegates" {

    function update( required struct data ) {
        return populate( memento: data, ignoreEmpty: true )
    }

    function updateFromJson( required string json ) {
        return populateFromJSON( JSONString: json, trustedSetter: true )
    }

}
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
component delegates="Population@coreDelegates" {

    function update( required struct data ) {
        return populate( memento: data, ignoreEmpty: true )
    }

    function updateFromJson( required string json ) {
        return populateFromJSON( JSONString: json, trustedSetter: true )
    }

}
```

{% endtab %}
{% endtabs %}

***

## StringUtil

**WireBox ID:** `StringUtil@coreDelegates`

String manipulation and formatting utilities.

| Method                             | Description                                                         |
| ---------------------------------- | ------------------------------------------------------------------- |
| `prettySql( target )`              | Formats a SQL string with newlines and indentation for readability. |
| `slugify( str, maxLength, allow )` | Creates a URL-safe slug. `maxLength=0` means no limit.              |
| `camelCase( target )`              | Converts `snake_case` or `kebab-case` to `camelCase`.               |
| `headline( target )`               | Converts a delimited or cased string to `Title Case With Spaces`.   |
| `ucFirst( target )`                | Uppercases the first character of a string.                         |
| `lcFirst( target )`                | Lowercases the first character of a string.                         |
| `kebabCase( target )`              | Converts a string to `kebab-case`.                                  |
| `snakeCase( target, delimiter )`   | Converts a string to `snake_case` (delimiter defaults to `_`).      |
| `pluralize( word )`                | Returns the plural form of an English word.                         |
| `singularize( word )`              | Returns the singular form of an English word.                       |

{% tabs %}
{% tab title="BoxLang" %}

```java
class delegates="StringUtil@coreDelegates" {

    function getPageSlug( required string title ) {
        return slugify( title, 100 )
        // "My Cool Post!" -> "my-cool-post"
    }

    function getTableName( required string modelName ) {
        return pluralize( snakeCase( modelName ) )
        // "UserProfile" -> "user_profiles"
    }

}
```

{% endtab %}

{% tab title="CFML" %}

```cfscript
component delegates="StringUtil@coreDelegates" {

    function getPageSlug( required string title ) {
        return slugify( title, 100 )
        // "My Cool Post!" -> "my-cool-post"
    }

    function getTableName( required string modelName ) {
        return pluralize( snakeCase( modelName ) )
        // "UserProfile" -> "user_profiles"
    }

}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://coldbox.ortusbooks.com/digging-deeper/delegates/core-delegates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.