index

Types

The Types module defines common utility types used throughout the @ts-rust/std package. It exports foundational types such as Primitive, Cloneable, Clone, Recoverable, and MaybePromise, which provide building blocks for type-safe programming in TypeScript. Inspired by Rust's type system, these types enable better handling of cloning, error recovery, and synchronous/asynchronous value interoperability. Use this module to leverage these utility types in your TypeScript applications for more robust and predictable code.

Interfaces

Interface Description

Interface	Description
Clone	Defines a type `T` that is cloneable, providing a method to create a new, independent instance of itself. The Clone interface ensures that any type implementing it can produce a duplicate of its current instance via the `clone` method. The type `T` represents the specific type of the implementing instance. Similar to Rust's `Clone` trait, this interface is intended for types that need explicit duplication logic (e.g., objects or complex structures), as opposed to Primitive types, which are implicitly copied by value. Unlike reference types that might share state, a clone implementation should produce a distinct instance, though the depth of the copy (shallow or deep) is left to the implementor. `T` is the type of the instance that implements this interface. Typically, this is the class or type itself (e.g., a class `MyType` would implement `Clone<MyType>`). Example `class MyType implements Clone<MyType> { constructor(public value: number) {} clone(this: MyType): MyType { return new MyType(this.value); } } const original = new MyType(42); const duplicate = original.clone(); expect(duplicate.value).toBe(original.value); // same value expect(duplicate).not.toBe(original); // different reference`
Recoverable	Defines a type `T` that is recoverable, providing error handling capabilities for potentially failing operations. The Recoverable interface ensures that any type implementing it can handle errors gracefully through the `catch` method, allowing for fallback values or alternative logic when operations fail. The type parameter `T` represents the successful result type that would be produced in the absence of errors. Similar to JavaScript's Promise error handling pattern, this interface standardizes error recovery across different implementation types. It allows consuming code to safely handle both the successful and error paths without needing to know the specific error handling mechanisms of the underlying implementation. The `T` type parameter represents the successful value type that will be resolved if no error occurs. The `R` type parameter in the `catch` method represents the type that will be produced by the error handler when an error is caught. Example class Result<T> implements Recoverable<T> { constructor(private value: T \| Error) {} catch<R>(onrejected: (reason: unknown) => R): Promise<T \| R> { if (this.value instanceof Error) { return Promise.resolve(onrejected(this.value)); } return Promise.resolve(this.value); } } // Success case const success = new Result<number>(42); const value = await success.catch((err) => -1); expect(value).toBe(42); // Original value returned // Error case const failure = new Result<number>(new Error("Failed")); const fallback = await failure.catch((err) => -1); expect(fallback).toBe(-1); // Fallback value from error handler

Clone

Defines a type T that is cloneable, providing a method to create a new, independent instance of itself.

The Clone interface ensures that any type implementing it can produce a duplicate of its current instance via the clone method. The type T represents the specific type of the implementing instance.

Similar to Rust's Clone trait, this interface is intended for types that need explicit duplication logic (e.g., objects or complex structures), as opposed to Primitive types, which are implicitly copied by value. Unlike reference types that might share state, a clone implementation should produce a distinct instance, though the depth of the copy (shallow or deep) is left to the implementor.

T is the type of the instance that implements this interface. Typically, this is the class or type itself (e.g., a class MyType would implement Clone<MyType>).

Example

class MyType implements Clone<MyType> {
  constructor(public value: number) {}

  clone(this: MyType): MyType {
    return new MyType(this.value);
  }
}

const original = new MyType(42);
const duplicate = original.clone();
expect(duplicate.value).toBe(original.value); // same value
expect(duplicate).not.toBe(original); // different reference

Recoverable

Defines a type T that is recoverable, providing error handling capabilities for potentially failing operations.

The Recoverable interface ensures that any type implementing it can handle errors gracefully through the catch method, allowing for fallback values or alternative logic when operations fail. The type parameter T represents the successful result type that would be produced in the absence of errors.

Similar to JavaScript's Promise error handling pattern, this interface standardizes error recovery across different implementation types. It allows consuming code to safely handle both the successful and error paths without needing to know the specific error handling mechanisms of the underlying implementation.

The T type parameter represents the successful value type that will be resolved if no error occurs. The R type parameter in the catch method represents the type that will be produced by the error handler when an error is caught.

Example

class Result<T> implements Recoverable<T> {
  constructor(private value: T | Error) {}

  catch<R>(onrejected: (reason: unknown) => R): Promise<T | R> {
    if (this.value instanceof Error) {
      return Promise.resolve(onrejected(this.value));
    }
    return Promise.resolve(this.value);
  }
}

// Success case
const success = new Result<number>(42);
const value = await success.catch((err) => -1);
expect(value).toBe(42); // Original value returned

// Error case
const failure = new Result<number>(new Error("Failed"));
const fallback = await failure.catch((err) => -1);
expect(fallback).toBe(-1); // Fallback value from error handler

Type Aliases

Type Alias Description

Type Alias	Description
Cloneable	Defines a type `T` that is cloneable, capable of being duplicated either implicitly as a Primitive or explicitly via a Clone implementation. The Cloneable type encompasses all values that can be cloned into a new, independent instance. It is a union of: Primitive type: JavaScript primitives (e.g., `number`, `string`, `boolean`) that are inherently copied by value through assignment. Clone types: Types that provide an explicit `clone()` method to create a duplicate instance of `T`. Inspired by Rust's distinction between `Copy` and `Clone`, this type captures: Implicit cloning: For Primitive types, where assignment (e.g., `let y = x`) creates a new copy due to their value semantics. Explicit cloning: For Clone types, where a `clone()` method must be invoked to produce a new instance. This type is broader than Clone alone, as it includes both implicitly copyable primitives and explicitly cloneable types. For non-primitive types, the `clone()` method should return a distinct instance, though the depth of the copy (shallow or deep) depends on the implementation. Example // Primitive satisfies Cloneable<number> const num: Cloneable<number> = 42; const numCopy = num; // Implicitly copied by value console.log(numCopy === num); // true (same value) // Class satisfies Cloneable<MyType> via Clone<MyType> class MyType implements Clone<MyType> { constructor(public value: number) {} clone(): MyType { return new MyType(this.value); } } const original = new MyType(42); const duplicate = original.clone(); console.log(duplicate.value === original.value); // true (same value) console.log(duplicate !== original); // true (different reference)
MaybePromise	Represents either a value of type `T` or a `Promise` resolving to `T`. The MaybePromise type provides flexibility when working with both synchronous and asynchronous values in a unified way. It allows functions and interfaces to accept either immediate values or promises without needing separate implementations, simplifying API design and improving interoperability between synchronous and asynchronous code. The `T` type parameter represents the actual value type, whether provided directly or eventually resolved from a Promise.
Primitive	Represents all JavaScript primitive types. A primitive is any value that is not an object and has no methods. Primitives are immutable (except for `symbol` properties) and are compared by value, not by reference. The `Primitive` type includes: `boolean` `string` `number` `bigint` `symbol` `null` `undefined` Objects, arrays, functions, and other reference types are not primitives. Use this type to enforce that a value belongs to one of these fundamental types.

Cloneable

Defines a type T that is cloneable, capable of being duplicated either implicitly as a Primitive or explicitly via a Clone implementation.

The Cloneable type encompasses all values that can be cloned into a new, independent instance. It is a union of:

Primitive type: JavaScript primitives (e.g., number, string, boolean) that are inherently copied by value through assignment.
Clone types: Types that provide an explicit clone() method to create a duplicate instance of T.

Inspired by Rust's distinction between Copy and Clone, this type captures:

Implicit cloning: For Primitive types, where assignment (e.g., let y = x) creates a new copy due to their value semantics.
Explicit cloning: For Clone types, where a clone() method must be invoked to produce a new instance.

This type is broader than Clone alone, as it includes both implicitly copyable primitives and explicitly cloneable types. For non-primitive types, the clone() method should return a distinct instance, though the depth of the copy (shallow or deep) depends on the implementation.

Example

// Primitive satisfies Cloneable<number>
const num: Cloneable<number> = 42;
const numCopy = num; // Implicitly copied by value
console.log(numCopy === num); // true (same value)

// Class satisfies Cloneable<MyType> via Clone<MyType>
class MyType implements Clone<MyType> {
  constructor(public value: number) {}
  clone(): MyType {
    return new MyType(this.value);
  }
}
const original = new MyType(42);
const duplicate = original.clone();
console.log(duplicate.value === original.value); // true (same value)
console.log(duplicate !== original); // true (different reference)

MaybePromise

Represents either a value of type T or a Promise resolving to T.

The MaybePromise type provides flexibility when working with both synchronous and asynchronous values in a unified way. It allows functions and interfaces to accept either immediate values or promises without needing separate implementations, simplifying API design and improving interoperability between synchronous and asynchronous code.

The T type parameter represents the actual value type, whether provided directly or eventually resolved from a Promise.

Primitive

Represents all JavaScript primitive types.

A primitive is any value that is not an object and has no methods. Primitives are immutable (except for symbol properties) and are compared by value, not by reference.

The Primitive type includes:

boolean
string
number
bigint
symbol
null
undefined

Objects, arrays, functions, and other reference types are not primitives. Use this type to enforce that a value belongs to one of these fundamental types.

Types

Interfaces​

Type Aliases​

Interfaces

Type Aliases