docs(README): add README to morpho-ts

README.md

@@ -6,27 +6,27 @@ A collection of Software Development Kits to ease interactions with the Morpho p
 
 ### Development
 
-- [`@morpho-org/morpho-ts`](./packages/morpho-ts/): TypeScript package to handle all things time & format-related
+- [**`@morpho-org/morpho-ts`**](./packages/morpho-ts/): TypeScript package to handle all things time & format-related
 
-- [`@morpho-org/blue-sdk`](./packages/blue-sdk/): Framework-agnostic package that defines Morpho-related entity classes (such as `Market`, `Token`, `Vault`)
-- [`@morpho-org/blue-sdk-viem`](./packages/blue-sdk-viem/): Viem-based augmentation of `@morpho-org/blue-sdk-viem` that exports (and optionally injects) viem-based fetch methods
-- [`@morpho-org/blue-sdk-ethers`](./packages/blue-sdk-ethers/): Ethers-based augmentation of `@morpho-org/blue-sdk-ethers` that exports (and optionally injects) ethers-based fetch methods
-- [`@morpho-org/blue-sdk-wagmi`](./packages/blue-sdk-wagmi/): Wagmi-based package that exports Wagmi (React) hooks to fetch Morpho-related entities
+- [**`@morpho-org/blue-sdk`**](./packages/blue-sdk/): Framework-agnostic package that defines Morpho-related entity classes (such as `Market`, `Token`, `Vault`)
+- [**`@morpho-org/blue-sdk-viem`**](./packages/blue-sdk-viem/): Viem-based augmentation of `@morpho-org/blue-sdk-viem` that exports (and optionally injects) viem-based fetch methods
+- [**`@morpho-org/blue-sdk-ethers`**](./packages/blue-sdk-ethers/): Ethers-based augmentation of `@morpho-org/blue-sdk-ethers` that exports (and optionally injects) ethers-based fetch methods
+- [**`@morpho-org/blue-sdk-wagmi`**](./packages/blue-sdk-wagmi/): Wagmi-based package that exports Wagmi (React) hooks to fetch Morpho-related entities
 
-- [`@morpho-org/simulation-sdk`](./packages/simulation-sdk/): Framework-agnostic package that defines methods to simulate interactions on Morpho (such as `Supply`, `Borrow`) and Morpho Vaults (such as `Deposit`, `Withdraw`)
-- [`@morpho-org/simulation-sdk-wagmi`](./packages/simulation-sdk-wagmi/): Wagmi-based extension of `@morpho-org/simulation-sdk` that exports Wagmi (React) hooks to fetch simulation states
+- [**`@morpho-org/simulation-sdk`**](./packages/simulation-sdk/): Framework-agnostic package that defines methods to simulate interactions on Morpho (such as `Supply`, `Borrow`) and Morpho Vaults (such as `Deposit`, `Withdraw`)
+- [**`@morpho-org/simulation-sdk-wagmi`**](./packages/simulation-sdk-wagmi/): Wagmi-based extension of `@morpho-org/simulation-sdk` that exports Wagmi (React) hooks to fetch simulation states
 
-- [`@morpho-org/bundler-sdk-viem`](./packages/bundler-sdk-viem/): Viem-based extension of `@morpho-org/simulation-sdk` that exports utilities to transform simple interactions on Morpho (such as `Blue_Borrow`) and Morpho Vaults (such as `MetaMorpho_Deposit`) into the required bundles (with ERC20 approvals, transfers, etc) to submit to the bundler onchain
+- [**`@morpho-org/bundler-sdk-viem`**](./packages/bundler-sdk-viem/): Viem-based extension of `@morpho-org/simulation-sdk` that exports utilities to transform simple interactions on Morpho (such as `Blue_Borrow`) and Morpho Vaults (such as `MetaMorpho_Deposit`) into the required bundles (with ERC20 approvals, transfers, etc) to submit to the bundler onchain
 
-- [`@morpho-org/blue-api-sdk`](./packages/blue-api-sdk/): GraphQL SDK that exports types from the [API's GraphQL schema](https://blue-api.morpho.org/graphql) and a useful Apollo cache controller
+- [**`@morpho-org/blue-api-sdk`**](./packages/blue-api-sdk/): GraphQL SDK that exports types from the [API's GraphQL schema](https://blue-api.morpho.org/graphql) and a useful Apollo cache controller
 
 ### Testing
 
-- [`@morpho-org/test`](./packages/test/): Framework-agnostic package that exports utilities to build test fixtures and spawn anvil forks as child processes
+- [**`@morpho-org/test`**](./packages/test/): Framework-agnostic package that exports utilities to build test fixtures and spawn anvil forks as child processes
 
-- [`@morpho-org/test-viem`](./packages/test-viem/): (Viem+vitest)-based package that defines utilities to spawn independent, concurrent anvil forks for each test, injecting the corresponding viem client as a test fixture
-- [`@morpho-org/test-ethers`](./packages/test-ethers/): Ethers-based extension of `@morpho-org/test-viem` that injects a test Ethers wallet as a test fixture alongside viem's anvil client
-- [`@morpho-org/test-wagmi`](./packages/test-wagmi/): Wagmi-based extension of `@morpho-org/test-viem` that injects a test Wagmi config as a test fixture alongside viem's anvil client
+- [**`@morpho-org/test-viem`**](./packages/test-viem/): (Viem+vitest)-based package that defines utilities to spawn independent, concurrent anvil forks for each test, injecting the corresponding viem client as a test fixture
+- [**`@morpho-org/test-ethers`**](./packages/test-ethers/): Ethers-based extension of `@morpho-org/test-viem` that injects a test Ethers wallet as a test fixture alongside viem's anvil client
+- [**`@morpho-org/test-wagmi`**](./packages/test-wagmi/): Wagmi-based extension of `@morpho-org/test-viem` that injects a test Wagmi config as a test fixture alongside viem's anvil client
 
 ## Authors
 

packages/blue-api-sdk/README.md

@@ -1,11 +1,29 @@
 # @morpho-org/blue-api-sdk
 
-[![npm package][npm-img]][npm-url]
-[![Downloads][downloads-img]][downloads-url]
-
-Useful utility package to easily integrate Morpho's GraphQL API either on a raw client or through Apollo.
-
-## Install
+<a href="https://www.npmjs.com/package/@morpho-org/blue-api-sdk">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/v/@morpho-org/blue-api-sdk?colorA=21262d&colorB=21262d&style=flat">
+        <img src="https://img.shields.io/npm/v/@morpho-org/blue-api-sdk?colorA=f6f8fa&colorB=f6f8fa&style=flat" alt="Version">
+    </picture>
+</a>
+<a href="https://github.com/wevm/@morpho-org/blue-api-sdk/blob/main/LICENSE">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/l/@morpho-org/blue-api-sdk?colorA=21262d&colorB=21262d&style=flat">
+        <img src="https://img.shields.io/npm/l/@morpho-org/blue-api-sdk?colorA=f6f8fa&colorB=f6f8fa&style=flat" alt="MIT License">
+    </picture>
+</a>
+<a href="https://www.npmjs.com/package/@morpho-org/blue-api-sdk">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/dm/@morpho-org/blue-api-sdk?colorA=21262d&colorB=21262d&style=flat">
+        <img src="https://img.shields.io/npm/dm/@morpho-org/blue-api-sdk?colorA=f6f8fa&colorB=f6f8fa&style=flat" alt="Downloads per month">
+    </picture>
+</a>
+<br />
+<br />
+
+GraphQL SDK that exports types from the [API's GraphQL schema](https://blue-api.morpho.org/graphql) and a useful Apollo cache controller.
+
+## Installation
 
 ```bash
 npm install @morpho-org/blue-api-sdk
@@ -15,11 +33,8 @@ npm install @morpho-org/blue-api-sdk
 yarn add @morpho-org/blue-api-sdk
 ```
 
----
-
 ## Getting Started
 
-
 ### Codegen
 
 Create a `codegen.ts` file and define your desired preset & plugins, importing types from `@morpho-org/blue-api-sdk`. Below is given 3 typically recommended configurations:

packages/morpho-ts/README.md

@@ -1,11 +1,29 @@
 # @morpho-org/morpho-ts
 
-[![npm package][npm-img]][npm-url]
-[![Downloads][downloads-img]][downloads-url]
+<a href="https://www.npmjs.com/package/@morpho-org/morpho-ts">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/v/@morpho-org/morpho-ts?colorA=21262d&colorB=21262d&style=flat">
+        <img src="https://img.shields.io/npm/v/@morpho-org/morpho-ts?colorA=f6f8fa&colorB=f6f8fa&style=flat" alt="Version">
+    </picture>
+</a>
+<a href="https://github.com/wevm/@morpho-org/morpho-ts/blob/main/LICENSE">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/l/@morpho-org/morpho-ts?colorA=21262d&colorB=21262d&style=flat">
+        <img src="https://img.shields.io/npm/l/@morpho-org/morpho-ts?colorA=f6f8fa&colorB=f6f8fa&style=flat" alt="MIT License">
+    </picture>
+</a>
+<a href="https://www.npmjs.com/package/@morpho-org/morpho-ts">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/dm/@morpho-org/morpho-ts?colorA=21262d&colorB=21262d&style=flat">
+        <img src="https://img.shields.io/npm/dm/@morpho-org/morpho-ts?colorA=f6f8fa&colorB=f6f8fa&style=flat" alt="Downloads per month">
+    </picture>
+</a>
+<br />
+<br />
 
-Lightweight package that includes TypeScript helpers to easily build apps around Morpho Blue & MetaMorpho.
+TypeScript package to handle all things time & format-related.
 
-## Install
+## Installation
 
 ```bash
 npm install @morpho-org/morpho-ts
@@ -15,13 +33,219 @@ npm install @morpho-org/morpho-ts
 yarn add @morpho-org/morpho-ts
 ```
 
----
+## Getting Started
 
-## Usage
+### Format
 
-### Utility
+The `format` utility provides a set of formatters to format numeric values in various human-readable forms.
 
-Refer to the specific documentation for detailed information on each utility:
+Here are all the available formatters:
 
-- [`format`](./src/format/format/README.md)
-- [`Time`](./src/time/README.md)
+- [**Hexadecimal Formatter**](#hex-formatter): Formats the value as a hexadecimal string.
+- [**Number Formatter**](#number-formatter): Formats the value as a standard decimal number.
+- [**Commas Formatter**](#commas-formatter): Formats the value as a comma-separated number.
+- [**Short Formatter**](#short-formatter): Formats the value in a short notation with units (e.g., `k`, `M`).
+- [**Percent Formatter**](#percent-formatter): Formats the value as a percentage.
+
+### Usage
+
+Each formatter can be accessed through the `format` object and provides chainable methods to customize the output. The formatted value can be obtained calling `.of(value)` for `number` or `.of(value, decimals)` for `bigint`.
+The return value will retain the nullability of the input value (giving priority to `value` over `decimals` for bigints, if none is defined), unless a `.default()` method is applied (refer to [Number Formatter](#2-number-formatter) for details).
+
+> [!Tip]
+> You can store the populated `of` function in a custom formatter:
+> ```typescript
+> import { format } from '@morpho-org/morpho-ts';
+> 
+> const formatDollar = format.short.digits(2).smallValuesWithCommas().unit("$").of
+> 
+> formatDollar(123456.789); // "$123.45k"
+> formatDollar(123456789n, 4); // "$12.34k"
+> ```
+
+
+#### Hex Formatter
+
+Formats a value as a hexadecimal string.
+
+```typescript
+import { format } from '@morpho-org/morpho-ts';
+
+format.hex.of(255n); // "ff"
+```
+
+> [!NOTE]
+> `decimals` will be ignored if this formatter is used with BigInts
+
+**Customization:**
+
+- `.prefix()`: Prepend the result with `0x`
+
+#### Number Formatter
+
+Formats a value as a standard number with optional customization.
+
+```typescript
+import { format } from '@morpho-org/morpho-ts';
+
+format.number.of(12345n, 2); // "123.45"
+format.number.of(123.45); // "123.45"
+```
+
+**Customization Methods:**
+
+- `.digits(number)`: Sets the number of decimal digits.
+- `.removeTrailingZero()`: Removes trailing zeros after the decimal.
+- `.min(number)`: Sets the minimum value; values below this will display as `< min`.
+- `.max(number)`: Sets the maximum value; values above this will display as `> max`.
+- `.sign()`: Adds a sign to the number (`+` or `-`).
+- `.unit(string)`: Adds a unit to the number (e.g., `$`, `%`).
+- `.locale(string)`: Formats the number according to the specified locale.
+- `.readable()`: Makes the value more readable for small numbers.
+- `.default(string)`: Sets a default value in case `value` (or `decimals`) is `null` or `undefined`.
+
+#### Commas Formatter
+
+Formats a value as a comma-separated string.
+
+```typescript
+import { format } from '@morpho-org/morpho-ts';
+
+format.commas.of(123456789n, 2); // "1,234,567.89"
+format.commas.of(1234567.89); // "1,234,567.89"
+
+format.commas.digits(2).unit("$").of(1234567); // "$1,234,567.00"
+```
+
+**Customization:**
+
+- Same as [Number Formatter](#number-formatter).
+
+#### Short Formatter
+
+Formats a value in a short notation with units (e.g., `k`, `M`, `B`).
+
+```typescript
+import { format } from '@morpho-org/morpho-ts';
+
+format.short.of(1234567890n, 2); // "12.34567890M"
+format.short.of(12345678.90); // "12.34567890M"
+
+format.short.digits(2).smallValuesWithCommas().of(1000000_00000000n, 8); // "1.00M"
+```
+
+**Customization:**
+
+- Same as [Number Formatter](#number-formatter).
+- `.smallValuesWithCommas()`: Formats small values using commas instead of short notation.
+
+#### Percent Formatter
+
+Formats a value as a percentage.
+
+```typescript
+import { format } from '@morpho-org/morpho-ts';
+
+format.percent.of(1000, 4); // "10"
+format.percent.of(0.1); // "10"
+
+format.percent.digits(1).sign().of(0.123456); // "+12.3%"
+```
+
+**Customization:**
+
+- Same as [Number Formatter](#number-formatter).
+
+### Time
+
+The `Time` utility provides a robust way to handle and convert time units in TypeScript, making it easier to work with various time durations.
+
+- [**Time Unit Conversion**](#converting-time-units): Convert between different time units such as milliseconds, seconds, minutes, hours, days, weeks, months, and years.
+- [**Wait**](#timewait): Pause execution for a specified amount of time.
+- [**Timestamp**](#timetimestamp): Get the current Unix timestamp as a bigint.
+- [**Period**](#period-types): Manage time periods
+
+
+#### Converting Time Units
+
+Each time unit has a `.from` method that allows you to convert from one unit to another.
+
+The following units are supported:
+
+- `ms` - milliseconds
+- `s` - seconds
+- `min` - minutes
+- `h` - hours
+- `d` - days
+- `w` - weeks
+- `mo` - months (assumed to be 31 days)
+- `y` - years (assumed to be 365 days)
+
+> [!Note]
+> The converter seamlessly handles both number and bigint inputs, ensuring the output type matches the type of the input value, preserving data consistency throughout conversions.
+
+Convert 1 hour to minutes:
+
+```typescript
+import { Time } from '@morpho-org/morpho-ts';
+
+const minutes = Time.h.from.min(1); // 60
+```
+
+Convert 5 days to hours:
+
+```typescript
+import { Time } from '@morpho-org/morpho-ts';
+
+const hours = Time.d.from.h(5n); // 120n
+```
+
+Convert 2 weeks to days:
+
+```typescript
+import { Time } from '@morpho-org/morpho-ts';
+
+const days = Time.w.from.d(2); // 14
+```
+
+#### `Time.wait`
+
+Pauses execution for the specified amount of milliseconds, eventually returning a specific value afterwards.
+
+**Usage:**
+
+```typescript
+import { Time } from '@morpho-org/morpho-ts';
+
+await Time.wait(1000); // Waits for 1 second
+const value = await Time.wait(1000, "Go"); // Waits for 1 second and returns "Go"
+```
+
+#### `Time.timestamp`
+
+Returns the current Unix timestamp in seconds as a bigint.
+
+**Usage:**
+
+```typescript
+import { Time } from '@morpho-org/morpho-ts';
+
+Time.timestamp(); // 1692671241n
+```
+
+#### Period Types
+
+The `Time` utility also provides types to define periods:
+
+- `Unit`: A type representing supported time units (`ms`, `s`, `min`, etc.).
+- `Period`: An object with `unit` and `duration` properties, defining a specific time period.
+- `PeriodLike`: A type that can either be a `Period` object or a `Unit`.
+
+You can convert a unit or a period-like object into a `Period`:
+
+```typescript
+import { Time } from '@morpho-org/morpho-ts';
+
+Time.toPeriod('h'); // { unit: 'h', duration: 1 }
+Time.toPeriod({ unit: 'min', duration: 15 }); // { unit: 'min', duration: 15 }
+```