@avento/ts-sdk

Infrastructure toolkit that absorbs cross-cutting complexity so product teams build features without reinventing the wheel or coupling apps to third-party libraries.

See SDK_DEFINITION.md for the full contract — design principles, scope, dependency rules, and success criteria.

Installation

npm install git+ssh://[email protected]/AventoSpace/avento-ts-sdk.git#v1.0.0

This package is proprietary and not published to npm. Install it as a Git dependency. The prepare script builds the package automatically during install.

Entry Points

Import only what you need. Every module is tree-shakable.

// Root — convenience barrel (everything re-exported here)
import { BaseError, ValidationError, NotFoundError } from "@avento/ts-sdk";
import type { DeepPartial, Nullable, AsyncResult } from "@avento/ts-sdk";

// Shared modules — preferred for tree-shaking
import { sleep, retry } from "@avento/ts-sdk/shared/async";
import { z, createSchema } from "@avento/ts-sdk/shared/validation";
import { createLogger } from "@avento/ts-sdk/shared/logging";
import { uuid, nanoid } from "@avento/ts-sdk/shared/ids";
import { sha256, hashPassword } from "@avento/ts-sdk/shared/crypto";
import { TypedEventEmitter } from "@avento/ts-sdk/shared/events";
import { format, parseDuration } from "@avento/ts-sdk/shared/dates";
import { pick, omit, unique } from "@avento/ts-sdk/shared/collections";
import { Ok, Err } from "@avento/ts-sdk/shared/result";
import { parseCookie } from "@avento/ts-sdk/shared/cookie";
import { buildUrl } from "@avento/ts-sdk/shared/url";
import { memoize } from "@avento/ts-sdk/shared/memoize";
import { truncate, slugify } from "@avento/ts-sdk/shared/string";
import { bubbleSort, quickSort } from "@avento/ts-sdk/shared/algorithms";

// Platform utilities
import { clipboard, isOnline } from "@avento/ts-sdk/platform/browser";
import { fsUtils } from "@avento/ts-sdk/platform/node";

// Domain ports + mock adapters (hexagonal)
import { MockObjectStorage } from "@avento/ts-sdk/domains/storage";
import { MockNotificationSender } from "@avento/ts-sdk/domains/notifications";
import { MockSessionStore } from "@avento/ts-sdk/domains/sessions";
import { MockBillingProvider } from "@avento/ts-sdk/domains/billing";

// Testing
import { createMockLogger, Builder, waitFor } from "@avento/ts-sdk/testing";

❌ Never import from internal or dist paths: @avento/ts-sdk/internal/* or @avento/ts-sdk/dist/*

Module Overview

Shared Modules

| Module | Description | |--------|-------------| | shared/async | Promise utilities: sleep, retry, timeout, parallel | | shared/validation | Zod-based schema validation: createSchema, commonSchemas | | shared/logging | Structured logging: createLogger, ConsoleLogger, NoopLogger, installConsoleOverrides | | shared/crypto | Hashing: sha256, hashPassword, verifyPassword, generateToken | | shared/ids | UUID and nanoid generation | | shared/events | Typed event emitter | | shared/dates | Date formatting and duration parsing | | shared/collections | pick, omit, unique, chunk, groupBy, Queue, Stack | | shared/algorithms | bubbleSort, quickSort, binarySearch, debounce, throttle | | shared/result | Ok, Err, Result discriminated union | | shared/memoize | memoize with TTL support | | shared/cookie | parseCookie, serializeCookie | | shared/url | buildUrl, parseUrl, isAbsolute | | shared/string | truncate, slugify, capitalize |

Domain Ports (Hexagonal)

| Domain | Port | Mock Adapter | |--------|------|------------| | domains/billing | BillingProvider | MockBillingProvider | | domains/storage | ObjectStorage | MockObjectStorage | | domains/notifications | NotificationSender | MockNotificationSender | | domains/sessions | SessionStore | MockSessionStore |

Platform Modules

| Module | Description | |--------|-------------| | platform/browser | clipboard, isOnline, onOnline, onOffline, fetchWithTimeout | | platform/node | fsUtils.readJSON, writeJSON, ensureDir, exists |

Testing Utilities

| Import | Description | |--------|-------------| | createMockLogger | Pre-configured mock logger for unit tests | | Builder<T> | Generic test data builder with fluent API | | wait | sleep alias for test helpers | | waitFor | Polls a predicate until it passes or times out |

Console Override

Enforce SDK logger usage at runtime in the consumer project:

import { installConsoleOverrides } from "@avento/ts-sdk/shared/logging";

installConsoleOverrides();
// console.log/warn/error now route through the SDK logger
// with a one-time deprecation warning per call site

ESLint Config

Forbid console.* at build time:

// eslint.config.mjs
import sdkEslint from "@avento/ts-sdk/eslint";
export default [...sdkEslint];

Architecture

The SDK follows a strict layered architecture. Dependencies flow downward only.

ROOT INDEX          re-exports every public symbol for convenience
     │
     ├── SHARED MODULES     async  crypto  dates  events  ids
     │          │           validation  logging  collections
     │          │           algorithms  string  result  memoize
     │          │           cookie  url
     │          │
     │          ├── CORE    errors  types
     │          │
     │          └── PLATFORM    browser  node
     │
     ├── DOMAINS     billing  storage  notifications  sessions
     │
     └── TESTING     mocks  builder  wait

Rules:

• core — imports NO other SDK module (only stdlib + externals)
• shared — may import core only
• domains — may import shared and core; never depends on other domains
• platform — isolated per environment; never depends on other modules
• testing — may import any module (test-only, not for production)

Design Principles

| # | Principle | |---|-----------| | P1 | Prefer functions over classes — no stateless classes in public API | | P2 | Zero side-effects on import — importing must never connect, log, or mutate globals | | P3 | Explicit typing — no any in public APIs | | P4 | Fail loudly — always throw typed BaseError subclasses | | P5 | Composition over inheritance — no abstract classes in public API | | P6 | No circular dependencies — enforced in CI | | P7 | Input immutability — never mutate arguments | | P8 | Deliberate dependencies — every external dep must be justified |

Development

npm run build       # Build with tsup (CJS + ESM + DTS)
npm test            # Run vitest (132+ tests)
npm run clean       # Remove dist/

Scripts

Scaffold a new monorepo project

Create a project with DDD + CQRS architecture, ESLint, Vitest, Prettier, and TypeScript pre-configured:

# from your new project directory:
node /path/to/@avento/ts-sdk/scripts/new-project.js my-app

# or if the SDK is installed as a dependency:
node node_modules/@avento/ts-sdk/scripts/new-project.js my-app

The scaffold generates:

my-app/
├── apps/api/              Application entry point
├── domains/
│   ├── users/             User management (DDD + CQRS)
│   └── orders/            Order management (DDD + CQRS)
├── infrastructure/        Shared infrastructure (database, messaging)
├── shared/                Shared domain primitives
├── packages/              Additional packages
├── docs/                  Architecture & rules documentation
├── eslint.config.mjs      ESLint (flat config, strict)
├── vitest.workspace.ts    Vitest workspace
├── tsconfig.base.json     TypeScript strict
└── .prettierrc            Prettier config