CashierFu-Kit

A TypeScript ORM library for CashierFu, providing a comprehensive set of data models and utilities for building point-of-sale and e-commerce applications.

Installation

npm install @cashierfu/kit

Also install a UUID generator:

# Node.js
npm install uuid

# React Native/Expo
npx expo install expo-crypto

# Browser: no installation needed (uses native crypto.randomUUID)

Features

• 🏪 Complete product catalog management data models (Catalogs, Products)
• 📦 Inventory management (Containers, Units)
• 👤 User and customer management
• 🏷️ Tagging and categorization
• 🎨 Image management with blurhash support
• 🔧 Configurable UUID generation (bring your own generator)
• 📝 TypeScript-first with full type safety
• 🌳 Tree-shakeable ESM and CommonJS builds
• 📦 Tiny bundle size (< 2KB gzipped for ESM)
• 🚫 Zero dependencies

Quick Start

import { Product } from '@cashierfu/kit'

// Create a new product
const product = new Product({
  title: 'Premium Coffee Beans',
  description: 'Whole-bean coffee roasted for espresso and drip brewing.',
  sku: 'COFFEE-001',
  images: [{ value: 'https://example.com/coffee.jpg' }],
  tags: [{ title: 'Coffee' }]
})

console.log(product.id) // Auto-generated UUID

Core Models

Product

Represents a product in your inventory with support for multiple barcodes, images, and metadata.

const product = new Product({
  title: 'Organic Green Tea',
  description: 'Loose-leaf sencha with a clean vegetal finish.',
  sku: 'TEA-001',
  catalogId: 'beverages-catalog-id',
  barcodes: [
    { type: 'UPC_A', value: '012345678905' }
  ],
  tags: [
    { title: 'Organic' },
    { title: 'Tea' }
  ],
  metadata: {
    origin: 'Japan',
    weight: '100g'
  }
})

Catalog

Organize products into catalogs with images and tags.

const catalog = new Catalog({
  title: 'Summer Collection 2025',
  description: 'Seasonal assortment for summer campaigns and featured displays.',
  images: [{ value: 'https://example.com/summer.jpg' }],
  tags: [
    { title: 'Seasonal' }
  ]
})

Container

Manage inventory containers (boxes, bins, pallets).

const container = new Container({
  title: 'Storage Bin A1',
  description: 'Primary backroom bin for boxed overstock inventory.',
  sku: 'BIN-A1',
  userId: 'warehouse-user',
  metadata: {
    location: 'Warehouse Section A',
    capacity: '50 items'
  }
})

Unit

Track inventory at the unit level, including status history/state tags through statuses.

const unit = new Unit({
  productId: 'prod-123',
  containerId: 'bin-a1',
  amount: 1299,
  description: 'Front-of-house sale unit ready for shelf placement.',
  sku: 'ITEM-001',
  statuses: [{ value: 'active' }],
  images: [
    {
      value: 'https://example.com/unit.jpg',
      blurhash: 'LEHV6nWB2yk8pyo0adR*.7kCMdnj'
    }
  ]
})

User

Customer and staff management with addresses and store associations.

const user = new User({
  email: '[email protected]',
  firstName: 'Jane',
  lastName: 'Smith',
  role: 'Admin',
  addresses: [
    {
      title: 'Home',
      address1: '123 Main St',
      city: 'Portland',
      state: 'OR',
      zip: '97201'
    }
  ],
  store: {
    title: 'Downtown Store',
    taxPercent: 8.5,
    stripeAccountId: 'acct_123'
  }
})

Supporting Models

Barcode

const barcode = new Barcode({
  type: 'UPC_A',
  value: '012345678905'
})

Image

const image = new Image({
  value: 'https://example.com/product.jpg',
  blurhash: 'LEHV6nWB2yk8pyo0adR*.7kCMdnj'
})

Tag

const tag = new Tag({
  title: 'Electronics'
})

Grid

Track grid-based inventory locations.

const grid = new Grid({
  title: 'A3',
  slots: [
    { index: 0, productId: 'prod-123' },
    { index: 1, productId: 'prod-456' }
  ]
})

Utilities

generateUuid

Generate UUIDs using your configured generator. Optionally configure a UUID generator before using this utility.

import { v4 as uuidv4 } from 'uuid'
import { configure, generateUuid } from '@cashierfu/kit'

// Configure first (required)
configure({ generateUuid: uuidv4 })

const id = generateUuid()

generateDateString

import { generateDateString } from '@cashierfu/kit'

const now = generateDateString() // ISO 8601 format

generateAlphanumeric

import { generateAlphanumeric } from '@cashierfu/kit'

const code = generateAlphanumeric(8) // e.g., "A3X9K2P7"

generateHexColor

import { generateHexColor } from '@cashierfu/kit'

const color = generateHexColor() // e.g., "#3A5F9E"

Configuration

UUID Generation (Optional)

Optionally configure a UUID generator before creating any models.

Node.js:

npm install uuid

import { configure } from '@cashierfu/kit'
import { v4 as uuidv4 } from 'uuid'

configure({ generateUuid: uuidv4 })

React Native/Expo:

npx expo install expo-crypto

import { configure } from '@cashierfu/kit'
import * as Crypto from 'expo-crypto'

configure({ generateUuid: () => Crypto.randomUUID() })

Browser:

import { configure } from '@cashierfu/kit'

configure({ generateUuid: () => crypto.randomUUID() })

Custom (for testing):

import { configure } from '@cashierfu/kit'

let counter = 1
configure({ generateUuid: () => `test-${counter++}` })

Model Relationships

User
├── addresses: UserAddress[]
└── store: UserStore

Catalog
├── images: Image[]
└── tags: Tag[]

Product
├── catalogId → Catalog
├── barcodes: Barcode[]
├── images: Image[]
└── tags: Tag[]

Container
├── images: Image[]
└── userId → User

Unit
├── productId → Product
├── containerId → Container
├── images: Image[]
└── statuses: Status[]

Static Properties

Several models include a static collection property for database integration:

• Product.collection = 'products'
• Catalog.collection = 'catalogs'
• Container.collection = 'containers'
• Unit.collection = 'units'
• User.collection = 'users'

TypeScript Support

All models are written in TypeScript and include full type definitions. Every class constructor accepts a Partial<T> type, allowing you to create instances with only the properties you need:

// Minimal product
const product1 = new Product({ title: 'Simple Product' })

// Full product with all properties
const product2 = new Product({
  title: 'Complete Product',
  sku: 'PROD-001',
  catalogId: 'cat-123',
  barcodes: [],
  images: [],
  tags: [],
  metadata: {},
  favorites: []
})

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run watch

# Run tests with coverage
npm run coverage

# Build the library (dual ESM + CJS)
npm run build

# Generate API documentation
npm run docs

# Check bundle size
npm run size

# Lint code
npm run lint

# Fix linting issues
npm run fix

Documentation

• API Documentation - Generated TypeDoc documentation
• Migration Guide - Version migration guides
• Quick Reference - Quick reference for all models
• Contributing - Contributing guidelines

License

ISC

Author

Jay Deaton