@esposter/shared 4.3.2 → 4.4.0

package/README.md

@@ -5,12 +5,14 @@
 [![NPM downloads][badge-npm-downloads]][url-npm]
 [![NPM Unpacked Size (with version)][badge-npm-unpacked-size]][url-npm]
 
-Shared TypeScript utilities, types, and error classes for the Esposter platform. Works in both browser and server environments.
+Shared TypeScript utilities, types, and error classes for the Esposter platform.
+
+Design notes live in [the specs](https://github.com/Esposter/Esposter/tree/main/openspec/specs/shared).
 
 ## Table of Contents
 
 - 🚀 [Getting Started](#getting-started)
-- 📖 [Documentation](#documentation)
+- 🧩 [Key Exports](#key-exports)
 - ⚖️ [License](#license)
 
 ---
@@ -21,11 +23,9 @@ Shared TypeScript utilities, types, and error classes for the Esposter platform.
 pnpm i @esposter/shared zod
 ```
 
-## <a name="documentation">📖 Documentation</a>
-
-We highly recommend you take a look at the [documentation](https://github.com/Esposter/Esposter/tree/main/openspec/specs/shared) to level up.
+Works in both browser and server environments.
 
-### Key Exports
+## <a name="key-exports">🧩 Key Exports</a>
 
 #### Error Classes
 
@@ -40,7 +40,7 @@ throw new InvalidOperationError(Operation.Read, file.name, zodError.message);
 ```ts
 import { takeOne } from "@esposter/shared";
 
-// Safe index access — throws on out-of-bounds instead of returning undefined
+// The first item, typed without `undefined`; an out-of-bounds index still yields `undefined` at runtime
 const first = takeOne(items);
 ```
 
@@ -49,7 +49,7 @@ const first = takeOne(items);
 ```ts
 import type { ToData, DeepOmit, GetPaths } from "@esposter/shared";
 
-// ToData<T> — strips class methods, returns plain data shape
+// ToData<T> — the plain data shape of T, with its `toJSON` method removed at every depth
 type RawColumn = ToData<Column>;
 ```
 
@@ -74,17 +74,6 @@ import { capitalize, truncate, toKebabCase } from "@esposter/shared";
 import { getResult, getResultAsync, withFinalizer } from "@esposter/shared";
 ```
 
-### Commands
-
-Run from `packages/shared/`:
-
-```bash
-pnpm build        # compile to dist/
-pnpm test         # vitest watch mode (coverage is run from the repo root)
-pnpm lint:fix     # auto-fix lint
-pnpm typecheck    # type check
-```
-
 ## <a name="license">⚖️ License</a>
 
 This project is licensed under the [Apache-2.0 license](https://github.com/Esposter/Esposter/blob/main/LICENSE).