readme.md for @tsclass/tsclass

A comprehensive, domain-driven TypeScript type library that gives your projects consistent, battle-tested interfaces for business logic, finance, networking, content management, and more — all in one place. 🚀

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm install @tsclass/tsclass

npm install @tsclass/tsclass

🧩 Module Overview

@tsclass/tsclass is organized into 12 domain modules, each focusing on a specific area. Import only what you need:

import {
  business,
  finance,
  network,
  content,
  container,
  code,
  database,
  descriptors,
  events,
  general,
  saas,
  storage,
  website,
} from '@tsclass/tsclass';

Additionally, the library re-exports the entire type-fest collection plus a few custom utility types:

import type { typeFest, typeFestOwn } from '@tsclass/tsclass';

📚 Modules in Detail

🏢 `business` — Contacts, Contracts, Documents & More

The business module models real-world entities like people, companies, addresses, contracts, letters, and projects.

Contacts

Type	Description
`TContact`	Discriminated union of `TPerson \| TCompany`
`TPerson`	A person with name, salutation, sex, optional legal proxy
`TCompany`	A company with registration details and lifecycle status (`planned → founding → active → liquidation → closed`)
`IAddress`	Physical address with optional GPS coordinates
`TSocialLinks`	Social media link (`facebook`, `twitter`, `linkedin`, or custom)
`TRegistrationDetails`	VAT ID, registration ID, and registration name

import { business } from '@tsclass/tsclass';

const company: business.TCompany = {
  type: 'company',
  name: 'Acme Corp',
  address: {
    streetName: 'Innovation Blvd',
    houseNumber: '42',
    postalCode: '28199',
    city: 'Bremen',
    country: 'Germany',
    countryCode: 'DE',
  },
  description: 'Builds amazing things',
  registrationDetails: {
    vatId: 'DE123456789',
    registrationId: 'HRB 12345',
    registrationName: 'Amtsgericht Bremen',
  },
  status: 'active',
  foundedDate: { day: 1, month: 6, year: 2020 },
};

Documents & Letters

Type	Description
`TDocumentEnvelope<TYPE, FIELDS>`	Base generic for all documents — includes `id`, `versionInfo`, `language`, `pdf`, `objectActions`
`TLetterEnvelope<TYPE, FIELDS>`	Extends document envelope with `from`, `to`, `subject`, and optional cover sheet
`TLetterSimple`	A simple letter
`TLetter`	Union of `TLetterSimple \| finance.TInvoice`
`IPdf`	PDF with `name`, `id`, `metadata`, and `buffer` (Uint8Array)

Contracts

Type	Description
`TContract`	Union of all contract types
`TEmploymentContract`	Employment terms including compensation, position, probation
`TNDAContract`	Non-disclosure agreement with confidentiality terms
`TServiceContract`	Service agreement with scope, deliverables, payment terms
`TLeaseContract`	Property lease with address, rent, and deposit
`TContractParty`	A party to a contract, with signing order and signature status
`TContractParagraph`	Individual contract paragraph/clause

Jobs & Projects

Type	Description
`IJob`	Full job posting with salary, requirements, languages, and scraping history
`ISalaryInfo`	Salary range with currency and period
`IProject`	Software/business project with domain, social links, and tags

💰 `finance` — Invoices, Payments, Currencies & Stock Prices

Everything money-related: invoices, credit notes, bank accounts, expenses, and market data.

Accounting Documents

Type	Description
`TAccountingDoc`	Union of `TInvoice \| TCreditNote \| TDebitNote \| TSelfBilledInvoice`
`TInvoice`	Standard invoice
`TCreditNote`	Credit note
`TDebitNote`	Debit note
`TSelfBilledInvoice`	Self-billed invoice
`TAccountingDocItem`	Line item with position, quantity, net price, VAT
`TAccountingDocStatus`	`'draft' \| 'issued' \| 'paid' \| 'canceled' \| 'refunded'`

import { finance } from '@tsclass/tsclass';

const item: finance.TAccountingDocItem = {
  position: 1,
  name: 'Consulting Services',
  unitType: 'hour',
  unitQuantity: 40,
  unitNetPrice: 150,
  vatPercentage: 19,
};

Payments & Banking

Type	Description
`ISepaConnection`	SEPA bank details (IBAN, BIC)
`IPayPalConnection`	PayPal email connection
`IPaymentOptionInfo`	Available payment methods
`ICheckingAccount`	Bank account with currency and transactions
`ITransaction`	A financial transaction

Other Finance Types

Type	Description
`TCurrency`	Union of ~170 ISO 4217 currency codes (including crypto: `BTC`, `ETH`, `ADA`, etc.)
`IStockPrice`	Real-time stock quote with market state, exchange info, and provider
`IExpenseItem`	Expense line item
`IVoucher`	Expense voucher/receipt

import { finance } from '@tsclass/tsclass';

const stock: finance.IStockPrice = {
  ticker: 'AAPL',
  price: 195.83,
  currency: 'USD',
  change: 2.47,
  changePercent: 1.28,
  previousClose: 193.36,
  timestamp: new Date(),
  provider: 'Yahoo Finance',
  marketState: 'REGULAR',
  exchange: 'NASDAQ',
  exchangeName: 'NASDAQ Global Select',
};

🌐 `network` — DNS, Certificates, SSH, JWT & HTTP

Types for infrastructure, networking, and web request/response handling.

Type	Description
`ICert`	SSL/TLS certificate with keys and CSR
`IDnsRecord`	DNS record with type, value, and DNSSEC status
`TDnsRecordType`	All common DNS record types (`A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `CAA`, `HTTPS`, etc.)
`IDnsChallenge`	DNS challenge for ACME verification
`IConvenientDnsProvider`	DNS provider interface with ACME challenge methods
`IDomainDelegation`	Parsed domain components (subdomain, domain, public suffix)
`ICnameDescriptor`	CNAME proxy configuration with optional SSL
`IReverseProxyConfig`	Reverse proxy config with authentication
`ISshKey`	SSH key pair
`IJwtKeypair`	JWT signing key pair (PEM format)
`INetworkNode`	Network node with IPv4/IPv6 and security level
`IDevice`	Network device with resolution and manufacturer
`ISimpleRequest` / `ISimpleResponse`	Simplified HTTP request/response
`IRenderFunction`	`(req: ISimpleRequest) => Promise<ISimpleResponse>`

import { network } from '@tsclass/tsclass';

const record: network.IDnsRecord = {
  name: 'example.com',
  type: 'A',
  value: '93.184.216.34',
  dnsSecEnabled: true,
};

🔐 `authentication` — Claims & JWT Processing

Type	Description
`IClaim`	JWT payload with `userName`, `userId`, `validUntil`, `roles`
`IProcessedClaim`	Verified JWT with original token, decoded claim, and `signed` flag

📦 `container` — Docker & OCI Containers

Type	Description
`IContainer`	Container image reference (registry, tag, version, labels)
`IVolumeMount`	Host-to-container volume mapping

📝 `content` — Articles, Authors & Documentation

Type	Description
`IArticle<T>`	Content article with title, body, tags, optional featured image, and generic reference object
`IAuthor`	Author with name, birthday, and article list
`IDocumentationSet`	Collection of articles forming a documentation set

🗄️ `database` — MongoDB, Object Lifecycle & Wrappers

Type	Description
`IMongoDescriptor`	MongoDB connection string and credentials
`IObjectAction`	Audit trail entry: timestamp, userId, action name, message
`IObjectStatus`	Object lifecycle status (`active \| inactive \| hidden \| markedForDeletion`) with scheduled deletion
`IWrappedData<T>`	Generic data wrapper

🔧 `descriptors` — Service Connection Descriptors

A convenience aggregation module that collects connection descriptors from across the library, plus adds its own.

Type	Description
`IMongoDescriptor`	Re-exported from `database`
`IStorageDescriptor`	Re-exported from `storage`
`IS3Descriptor`	Deprecated alias for `IStorageDescriptor`
`ICloudflareDescriptor`	Cloudflare API auth token
`ILetterExpressDescriptor`	LetterExpress API credentials

📡 `events` — Domain Event Types

Type	Description
`IEvent_Contract`	Contract/subscription event
`IEvent_Money`	Monetary transfer event (SEPA, credit card, PayPal, Cardano)
`IEvent_Release`	Software release event (npm, Docker, App Store, Google Play)
`IEvent_Request`	HTTP request event with duration
`IEvent_Session`	User session event (new or reactivated)
`IEvent_User`	User event placeholder

📅 `general` — Foundational Types

Type	Description
`IDate`	Simple calendar date (`day`, `month`, `year`) — used across many modules
`ITime`	Time representation (placeholder for extension)

☁️ `saas` — Products & Subscription Plans

Type	Description
`IProduct`	SaaS product with features, landing page, and publisher
`IProductFeature`	Product feature block with heading and link
`ISubscriptionPlan`	Subscription plan with pricing terms, units, and contained products

💾 `storage` — S3-Compatible Storage

Type	Description
`IStorageDescriptor`	S3-compatible storage connection (endpoint, credentials, bucket, region)
`IS3Descriptor`	⚠️ Deprecated — use `IStorageDescriptor`

🌍 `website` — Links, Menus & Navigation

Type	Description
`ILink`	Hyperlink with URL, text, icon, and target
`ILinkBlock`	Titled group of links
`IMenuItem<T, U>`	Menu item with async action callback

🏗️ Architecture: The Document Hierarchy

One of the most powerful aspects of @tsclass/tsclass is its layered document type hierarchy. Documents build on each other using generic envelope types:

TDocumentEnvelope           ← Base: id, version, language, PDF, object actions
  └── TLetterEnvelope       ← Adds: from, to, subject, cover sheet
        └── TAccountingDocEnvelope  ← Adds: items, currency, payment, due date
              ├── TInvoice
              ├── TCreditNote
              ├── TDebitNote
              └── TSelfBilledInvoice
  └── TContractEnvelope     ← Adds: parties, paragraphs, dates
        ├── TEmploymentContract
        ├── TNDAContract
        ├── TServiceContract
        └── TLeaseContract

This means an TInvoice automatically has all the fields of a letter (sender, recipient, subject) and a document (version info, PDF attachment, audit trail). No duplication, full consistency. ✨

🔧 Utility Types

The library also re-exports type-fest in its entirety plus two custom utility types:

Type	Description
`typeFestOwn.SecondArgument<T>`	Extracts the second argument type from a function
`typeFestOwn.ValueType<T>`	Extracts the value type from an object type

import type { typeFest, typeFestOwn } from '@tsclass/tsclass';

type MyPartial = typeFest.PartialDeep<SomeComplexType>;
type Val = typeFestOwn.ValueType<{ a: number; b: string }>; // number | string

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md for @tsclass/tsclass

Issue Reporting and Security

Install

🧩 Module Overview

📚 Modules in Detail

🏢 business — Contacts, Contracts, Documents & More

Contacts

Documents & Letters

Contracts

Jobs & Projects

💰 finance — Invoices, Payments, Currencies & Stock Prices

Accounting Documents

Payments & Banking

Other Finance Types

🌐 network — DNS, Certificates, SSH, JWT & HTTP

🔐 authentication — Claims & JWT Processing

📦 container — Docker & OCI Containers

📝 content — Articles, Authors & Documentation

🗄️ database — MongoDB, Object Lifecycle & Wrappers

🔧 descriptors — Service Connection Descriptors

📡 events — Domain Event Types

📅 general — Foundational Types

☁️ saas — Products & Subscription Plans

💾 storage — S3-Compatible Storage

🌍 website — Links, Menus & Navigation