@thalorlabs/types

A TypeScript types package for ThalorLabs projects, providing shared type definitions and Zod schemas.

Installation

npm install @thalorlabs/types

Usage

Import All Types

import {
  Address,
  Location,
  Waterfall,
  WaterfallCore,
  WaterfallPartial,
  EWaterfallTags,
  EWaterfallAccessDifficulty,
  EAustralianState,
  ECountryCode,
  MongoMeta,
} from '@thalorlabs/types';

Import Individual Types

import { Address } from '@thalorlabs/types/types/Address';
import { Location } from '@thalorlabs/types/types/Location';
import { Waterfall } from '@thalorlabs/types/types/Waterfall';
import { EWaterfallTags } from '@thalorlabs/types/types/Waterfall';
import { EAustralianState } from '@thalorlabs/types/enums/EAustralianState';
import { ECountryCode } from '@thalorlabs/types/enums/ECountryCode';

Available Types

Core Types

| Type | Description | Usage | | ----------- | ---------------------------------------------------------------- | ------------------------------ | | Address | Address schema with Australian state and country support | Address.parse(addressData) | | Location | Geographic location with coordinates and Google Maps integration | Location.parse(locationData) | | MongoMeta | MongoDB metadata fields (_id, createdAt, updatedAt) | MongoMeta.parse(metaData) |

Waterfall Types

| Type | Description | Usage | | ------------------ | -------------------------------------------- | ------------------------------------ | | WaterfallCore | Core waterfall data without MongoDB metadata | WaterfallCore.parse(waterfallData) | | Waterfall | Complete waterfall with MongoDB metadata | Waterfall.parse(waterfallData) | | WaterfallPartial | Partial waterfall for update operations | WaterfallPartial.parse(updateData) |

Enums

| Enum | Description | Values | | ---------------------------- | --------------------------------- | ------------------------------------------------------------- | | EWaterfallTags | Waterfall feature tags | DOG_FRIENDLY, KID_FRIENDLY, WHEELCHAIR_ACCESSIBLE, etc. | | EWaterfallAccessDifficulty | Access difficulty levels | EASY, MODERATE, HARD | | EAustralianState | Australian states and territories | NSW, VIC, QLD, SA, WA, TAS, NT | | ECountryCode | Supported country codes | AU, NZ |

Examples

Address Validation

import { Address } from '@thalorlabs/types';

const addressData = {
  streetNumber: '123',
  streetName: 'Main Street',
  suburb: 'Sydney',
  state: 'NSW',
  postcode: '2000',
  country: 'AU',
};

const address = Address.parse(addressData);
// Returns validated address object

Waterfall Creation

import {
  WaterfallCore,
  EWaterfallTags,
  EWaterfallAccessDifficulty,
} from '@thalorlabs/types';

const waterfallData = {
  name: 'Fitzroy Falls',
  address: {
    suburb: 'Fitzroy Falls',
    state: 'NSW',
    postcode: '2577',
    country: 'AU',
  },
  location: {
    latitude: -34.6531,
    longitude: 150.4789,
  },
  tags: [EWaterfallTags.VIEWING_PLATFORM, EWaterfallTags.KID_FRIENDLY],
  accessDifficulty: EWaterfallAccessDifficulty.EASY,
  url: 'https://example.com/fitzroy-falls',
};

const waterfall = WaterfallCore.parse(waterfallData);

MongoDB Integration

import { Waterfall, MongoMeta } from '@thalorlabs/types';
import { ObjectId } from 'bson';

const waterfallWithMeta = {
  ...waterfallData,
  _id: new ObjectId(),
  createdAt: new Date(),
  updatedAt: new Date(),
};

const fullWaterfall = Waterfall.parse(waterfallWithMeta);

Project Structure

src/
├── index.ts              # Main exports
├── types/                # Type definitions
│   ├── Address.ts        # Address schema
│   ├── Location.ts       # Location schema
│   ├── MongoMeta.ts      # MongoDB metadata
│   └── Waterfall.ts      # Waterfall schemas and enums
└── enums/                # Enum definitions
    ├── EAustralianState.ts
    └── ECountryCode.ts

TypeScript Support

This package includes full TypeScript support with:

• Complete type definitions
• Zod schema validation
• IntelliSense support
• Compile-time type checking

Third-Party Types Policy

This package only contains ThalorLabs contract types - the shapes we guarantee between our microservices and clients.

✅ What belongs here:

• WeatherResponse - our normalized weather data contract
• PaymentIntent - our payment processing contract
• UserProfile - our user data contract
• Domain-specific types like Waterfall, Address, Location

❌ What does NOT belong here:

• OpenWeather API response types
• Stripe webhook payload types
• GitHub API response types
• Any external service's raw API types

Why this matters:

• Stable contracts - Clients consume our normalized types, not third-party APIs
• Encapsulation - Third-party changes don't break our entire ecosystem
• Maintainability - Update third-party integrations in one service, not everywhere

Keep third-party API types local to the service that consumes them, not in this shared types package.