ts-utils

A collection of helper functions and types. To use any of the following, simply import into your project like so:

import { safeAwait, Ok, Err, Result } from '@crbroughton/ts-utils'

Installation

To install ts-utils with Bun, run the following command:

bun i -D @crbroughton/ts-utils

result

The result directory contains a Rust-inspired Result type system for explicit error handling:

• Result<T, E> - A type representing either success (Ok<T>) or failure (Err<E>)
• Ok(value) - Creates a successful result containing a value
• Err(error) - Creates a failed result containing an error
• safeAwait(promise) - Safely executes a Promise and returns a Result instead of throwing
• isOk(result) - Type guard to check if a Result is Ok
• isErr(result) - Type guard to check if a Result is Err
• ok(result) - Extracts the value from a Result if Ok, otherwise returns null
• err(result) - Extracts the error from a Result if Err, otherwise returns null

Example usage:

// Basic usage with safeAwait
const result = await safeAwait(fetch('/api/data'))
if (isErr(result)) {
  console.error('Fetch failed:', result.error)
  return
}
const response = result.value

// Creating Results manually
const success = Ok(42) // { ok: true, value: 42 }
const failure = Err('Something went wrong') // { ok: false, error: 'Something went wrong' }

// Type guards for safe access
if (isOk(result)) {
  console.log(result.value) // TypeScript knows this is the success type
}

// Convenient extraction
const user = ok(result) // User | null
const error = err(result) // Error | null

enum

The enum directory contains the following:

• EnumLike - A helper type to define enum-like objects
• createEnum - A function to create enum-like object

It is intended that you'll only need to interface with the createEnum function, however the EnumLike type has been exported if you find yourself requiring it.

utils

The utils directory for now only contains the Prettify type, which will improve your experience when hovering over type to get their underlying type information.

Zod

The Zod directly currently contains only a single function, the zodObjectBuilder function, which is a helper to generate objects from a Zod object schema. Use this function for whenever you need to generate objects but don't want to see the entire object in your code. This function support both full and partial schema support. Below is an example of zodObjectBuilder in action with it's various use-cases.

// Define a schema
const UserSchema = z.object({
  id: z.string().default('1'),
  name: z.string().default("Craig R Broughton"),
  email: z.string().email().default("[email protected]")
  settings: z.object({
    theme: z.enum(['light', 'dark']),
    notifications: z.boolean()
  }).default({
    theme: 'dark',
    notifications: true
  })
});

// Create default object(nested in an array) with no overrides
const defaultUsers = zodObjectBuilder({
  schema: UserSchema
});


// Create a single object with overrides
const user = zodObjectBuilder({
  schema: UserSchema,
  overrides: { name: 'John', settings: { theme: 'dark' } }
});

// Create multiple objects with overrides
const users = zodObjectBuilder({
  schema: UserSchema,
  overrides: [
    { name: 'John' },
    { name: 'Jane', settings: { theme: 'light' } }
  ]
});

// Preserve nested defaults with overrides
const userWithDefaults = zodObjectBuilder({
  schema: UserSchema,
  overrides: { name: 'John', settings: { theme: 'dark' } },
  config: { preserveNestedDefaults: true }
});

// Generate multiple objects with sequential values
const sequentialUsers = zodObjectBuilder({
  schema: UserSchema,
  options: {
    count: 3,
    transform: {
      id: (i) => `USER-${i + 1}`,
      name: (i) => `User ${i + 1}`
    }
  }
});

// Generate multiple batches with different transforms
const mixedUsers = zodObjectBuilder({
  schema: UserSchema,
  options: {
    batchTransform: [
      { 
        count: 2, 
        transform: {
          id: ({ index }) => `ADMIN-${index + 1}`,
          role: () => 'admin' as const
        }
      },
      { 
        count: 3, 
        transform: {
          id: ({ index }) => `USER-${index + 1}`,
          role: () => 'user' as const
        }
      }
    ]
  }
})

// Combine global transformations with batch transformations
const result = zodObjectBuilder({
  schema: UserSchema,
  config: {
    allowOverlappingTransforms: true
  },
  options: {
    transform: {
      email: ({ index }) => `global${index + 1}@example.com`
    },
    batchTransform: [
      {
        count: 2,
        transform: {
          id: ({ index }) => `FIRST-${index + 1}`
        }
      },
      {
        count: 1,
        transform: {
          id: ({ index }) => `SECOND-${index + 1}`
        }
      }
    ]
  }
})

Development Installation

bun install

To run:

bun run index.ts

This project was created using bun init in bun v1.1.27. Bun is a fast all-in-one JavaScript runtime.