Skip to main content

upp-defs -- Overview

What is upp-defs?​

upp-defs is the foundational library of the UnPisPas monorepo. It sits at the very bottom of the dependency graph: every other library and application in the workspace depends on it, but it depends on nothing except the build-time environment file. This zero-dependency design is intentional -- it guarantees that any code, anywhere in the monorepo, can safely import from @unpispas/upp-defs without pulling in Angular services, HTTP clients, or any other heavyweight dependency.

Think of upp-defs as the "shared vocabulary" of the entire system. It provides:

  • Application-wide constants -- URLs, tax rates, timing thresholds, API keys, TicketBAI registry data, printing defaults, and service-worker configuration. Every part of the system that needs to know "what is the backend URL?" or "what is the general VAT rate in Spain?" reads it from AppConstants rather than hard-coding it.
  • Pure utility functions -- UUID generation, CRC32 checksums, deep copy, string normalisation, base64/ArrayBuffer conversion, MySQL date helpers, and image-to-base64. These are stateless helpers used across data objects, views, login flows, and sync logic.
  • Price calculation engine -- PriceInfo handles multi-tax-rate price aggregation with proportional discounts. This is central to the ticket system (the core business domain) where every ticket, product, and discount needs correct tax breakdowns.
  • Tax ID validation -- TaxIdValidators implements the Spanish DNI, NIE, and CIF validation algorithms, used wherever the application collects or verifies a tax identifier.
  • Async synchronisation -- GlobalMutex provides key-based locking for serialising concurrent operations, preventing race conditions in async workflows.

Why it exists​

Without upp-defs, every library would need its own copy of constants, its own UUID generator, its own price calculator. That leads to:

  1. Inconsistency -- different tax rates or URLs in different places.
  2. Circular dependencies -- higher-level libraries importing from each other just to share a utility.
  3. Duplication -- the same algorithm implemented (and maintained) in multiple locations.

By placing all of this in a single, dependency-free library, the architecture enforces a clean dependency flow: upp-defs -> upp-base -> upp-data -> feature libs -> apps. No library ever needs to reach "sideways" or "downward" for a shared constant or utility.

What it exports​

ExportKindPurpose
AppConstantsStatic classAll application constants: URLs, tax rates, timings, API keys, service-worker config, TicketBAI registry, printing defaults, and more. Values come from hard-coded defaults or the build-time environment object.
GenericUtilsStatic classPure utility methods -- UUID generation, CRC32 checksum, deep copy, string normalisation (with memoisation), base64/ArrayBuffer conversion, MySQL date helpers, image-to-base64, and a fast non-cryptographic hash.
PriceInfoClassPrice calculation engine that accumulates amounts across multiple tax rates and applies proportional discounts. Used throughout the ticket system.
PriceTypeTypeThe shape returned by PriceInfo.price -- total value, sign, formatted string (integer/decimal parts), and full tax/discount breakdowns.
TaxIdValidatorsStatic classSpanish DNI, NIE, and CIF validation and normalisation.
GlobalMutexClassKey-based async mutex for serialising concurrent operations. Each key has an independent lock queue.
TaxesSplit / TaxesInfoTypesInternal types used by PriceInfo to represent per-rate and aggregated tax information.

Public API entry point​

The library re-exports everything through a single barrel file:

// libs/upp-defs/src/index.ts
export * from './lib/upp-defs.component';
export * from './app.constants';
export * from './app.utils';

app.constants.ts contains AppConstants. app.utils.ts contains GenericUtils, TaxIdValidators, GlobalMutex, PriceInfo, PriceType, and the tax-related types.

Importing​

From any library or application inside the monorepo:

import { AppConstants, GenericUtils, PriceInfo, TaxIdValidators, GlobalMutex } from '@unpispas/upp-defs';

The @unpispas/upp-defs path alias is configured in the root tsconfig.base.json and resolved by Nx at build time.

Dependency graph​

upp-defs  (zero internal dependencies)
  reads -> environments/environment.ts   (injected at build time)

All configuration that varies between build targets -- production vs development URLs, TicketBAI sandbox flags, Google Analytics IDs, the application version string -- is read from the environment object. This keeps upp-defs itself environment-agnostic: the same source code serves every deployment, with behaviour controlled entirely by the build configuration.

Where upp-defs sits in the monorepo​

                 +-----------+
                 | upp-defs  |   <-- you are here (zero deps)
                 +-----------+
                      |
                 +-----------+
                 | upp-base  |   (Angular services: HTTP, state, storage, platform)
                 +-----------+
                      |
                 +-----------+
                 | upp-data  |   (data model, sync, cache, login)
                 +-----------+
                      |
              +-------+-------+
              |               |
        +-----------+   +-----------+
        | feature/* |   | upp-wdgt  |   (feature libs, widgets)
        +-----------+   +-----------+
              |               |
        +---------------------+
        |   apps (POS, test)  |
        +---------------------+

Every arrow points downward. upp-defs is the only library that every other library can import without concern for circular dependencies.

When to use upp-defs directly​

You should import from upp-defs when you need:

  • A constant that applies across the application (URL, tax rate, threshold, API key).
  • A pure utility that has no dependency on Angular or any service (UUID, hash, date conversion, deep copy).
  • Price calculation with tax breakdowns.
  • Tax ID validation for Spanish identifiers.
  • A mutex for serialising async work by key.

If your code needs Angular services (HTTP, state, storage), look at upp-base instead. If it needs data objects or sync, look at upp-data.