tabletcommand-sync-settings

A TypeScript library for managing and formatting user settings in the Tablet Command ecosystem. This package centralizes the logic for computing user-specific settings by merging department configurations, user preferences, agency settings, and environmental configurations.

Installation

npm install tabletcommand-sync-settings

Usage

The primary API is formatSettings(), which merges department/user/agency data and environment config into a single settings object. convertToLegacy() then flattens that object into the key/value array format served by /api/sync/setting_feature.

import { formatSettings, convertToLegacy, EnvConfig } from "tabletcommand-sync-settings";

const envConfig: EnvConfig = {
  pn: pubNubConfig,
  wn: webNotificationConfig,
  zonehavenFeatureServiceUrl: process.env.NODE_ZONEHAVEN_FEATURE_SERVICE_URL ?? "",
};

const formatted = formatSettings(department, user, agency, envConfig, deviceType);
const legacyItems = convertToLegacy(formatted);

formatSettings(department, user, agency, envConfig, deviceType) returns a SettingFormatted object. convertToLegacy(item) returns a SettingItem[], the flattened {name, key, json} shape the mobile app's legacy sync endpoint expects.

Project Structure

src/
├── index.ts          # formatSettings(), convertToLegacy(), and conversion helpers
├── types.ts          # TypeScript interfaces for inputs (EnvConfig) and outputs (SettingFormatted, SettingItem, etc.)
└── test/             # unit tests (tsx --test)

Key Functions

| Function | Purpose | |---|---| | formatSettings | Merges department, user, agency, and envConfig into a single SettingFormatted object | | convertToLegacy | Flattens a SettingFormatted object into the legacy SettingItem[] array ({name, key, json}) served by /api/sync/setting_feature | | convertUserStealthStatus | Normalizes a raw stealth-status string into UserStealthStatus | | convertDepartmentReportOdometer | Normalizes a raw report-odometer string into DepartmentReportOdometer | | convertAccountIndustry | Normalizes a raw industry string into AccountIndustry |

Key Call-outs

EnvConfig vs. department — formatSettings reads two kinds of input differently. Per-department values (e.g. zonehaven.layerUrl) come from the department parameter, sourced from Mongo. Global, environment-sourced values that apply the same way to every department (e.g. pn/wn PubNub/webNotification config, zonehavenFeatureServiceUrl) are threaded in explicitly through the envConfig parameter instead, since they aren't stored per-department at all.

convertToLegacy is a passthrough, not a field-by-field mapper — for most entries, convertToLegacy pushes the entire sub-object from SettingFormatted into json (e.g. json: item.zonehaven for key 403), rather than picking individual fields. Any field added to a SettingFormatted sub-object (like SettingZonehaven) automatically flows through to the legacy payload without needing a separate change in convertToLegacy itself.

Type safety — Interfaces for both inputs and outputs live in src/types.ts. Type coverage is enforced at build time (typeCoverage.atLeast in package.json).

Development

npm run build

npm test

npm run lint

Package Maintenance

Upgrading Dependencies

Before publishing a new version, follow these steps to keep dependencies up to date:

1. Install npm-check-updates (one-time setup)

npm i -g npm-check-updates

2. Update Minor Versions

Run this command in the same folder where package.json is located:

npx ncu -i --target minor

Review and select packages that are safe to update, such as:

• Development tools: cspell, eslint, mocha, chai, @types/*
• Internal packages: tabletcommand-backend-models (e.g., 7.4.15 → 7.4.34)

3. Check for Major Version Updates

Run without the --target minor flag to see all available upgrades:

npx ncu -i

Evaluate each major version upgrade carefully:

Examples of Safe to Upgrade

• uuid: Compatible upgrades from v9 → v10 → v11 → v12 → latest
• mocha/chai: Generally compatible across versions
• Development dependencies: Usually safe to upgrade

Proceed with Caution

• @types/node: Match your Node.js environment version
  • Example: If running Node.js 22.x, use @types/node ^22.x.x, NOT ^25.x.x
• @esri/@arcgis packages: Do NOT upgrade without testing - breaking changes common
• redis packages: Incompatible changes between major versions
  • Note: Current test mocking libraries don't support the latest Node.js Redis package

4. Track Outdated Dependencies

For packages that cannot be safely upgraded:

• Create a story to track the outdated dependency
• Document why it can't be upgraded
• Note possible solutions or blockers

5. Verify Security Alerts

After updating and pushing changes, verify that Dependabot alerts are cleared:

https://github.com/TabletCommand/tabletcommand-sync-settings/security/dependabot

Best Practices

• Always test after upgrading dependencies
• Review changelogs for major version bumps
• Run the full test suite before publishing
• Keep @types/node aligned with your Node.js version
• Document any upgrade blockers or compatibility issues

Repository

https://github.com/TabletCommand/tabletcommand-sync-settings