@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

or

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.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.