@locusgraph/utils 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LocusGraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @locusgraph/utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Formatting and quota helpers LocusGraph apps share. No dependencies, no React.
+
+```bash
+pnpm add @locusgraph/utils
+```
+
+| Function | Example |
+|---|---|
+| `formatCents(4000)` | `$40.00` |
+| `formatMicroUsd(1_234_500)` | `$1.2345` (sub-cent amounts keep four places) |
+| `centsToMicroUsd(1000)` | `10000000` |
+| `formatCount(10450)` | `10,450` |
+| `pluralize(2, "key")` | `2 keys` |
+| `formatDate("2026-11-15T12:00:00Z", "Never")` | `Nov 15, 2026` (UTC; the fallback when empty or invalid) |
+| `quotaPercent({ used, included })` | 0–100, capped |
+| `quotaStatus({ used, included })` | `"ok"`, `"near"` from 80%, `"over"` past the allowance |
+| `balanceLevel(microUsd)` | `"empty"` at or below 0, `"low"` under $2, else `"fine"` |
+
+Money follows the platform's rules: prices and Stripe amounts are integer cents; wallet balances and charges are integer micro-USD ($1 = 1,000,000).

package/dist/dates.d.ts

@@ -0,0 +1 @@
+export declare function formatDate(value: string | number | Date | null | undefined, empty?: string): string;

package/dist/dates.js

@@ -0,0 +1,8 @@
+const mediumDate = new Intl.DateTimeFormat("en-US", { dateStyle: "medium", timeZone: "UTC" });
+export function formatDate(value, empty = "") {
+    if (value === null || value === undefined) {
+        return empty;
+    }
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? empty : mediumDate.format(date);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./dates.js";
+export * from "./money.js";
+export * from "./numbers.js";
+export * from "./quota.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./dates.js";
+export * from "./money.js";
+export * from "./numbers.js";
+export * from "./quota.js";

package/dist/money.d.ts

@@ -0,0 +1,6 @@
+export declare function formatCents(cents: number): string;
+export declare function formatMicroUsd(microUsd: number): string;
+export declare function centsToMicroUsd(cents: number): number;
+export type BalanceLevel = "fine" | "low" | "empty";
+export declare const lowBalanceMicroUsd = 2000000;
+export declare function balanceLevel(balanceMicroUsd: number, lowAtMicroUsd?: number): BalanceLevel;

package/dist/money.js

@@ -0,0 +1,26 @@
+const microUsdPerDollar = 1_000_000;
+const microUsdPerCent = 10_000;
+const usd = (fractionDigits) => new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: fractionDigits.min,
+    maximumFractionDigits: fractionDigits.max,
+});
+const wholeCentsFormat = usd({ min: 2, max: 2 });
+const subCentFormat = usd({ min: 2, max: 4 });
+export function formatCents(cents) {
+    return wholeCentsFormat.format(cents / 100);
+}
+export function formatMicroUsd(microUsd) {
+    const format = microUsd % microUsdPerCent === 0 ? wholeCentsFormat : subCentFormat;
+    return format.format(microUsd / microUsdPerDollar);
+}
+export function centsToMicroUsd(cents) {
+    return cents * microUsdPerCent;
+}
+export const lowBalanceMicroUsd = 2_000_000;
+export function balanceLevel(balanceMicroUsd, lowAtMicroUsd = lowBalanceMicroUsd) {
+    if (balanceMicroUsd <= 0)
+        return "empty";
+    return balanceMicroUsd < lowAtMicroUsd ? "low" : "fine";
+}

package/dist/numbers.d.ts

@@ -0,0 +1,2 @@
+export declare function formatCount(value: number): string;
+export declare function pluralize(count: number, singular: string, plural?: string): string;

package/dist/numbers.js

@@ -0,0 +1,7 @@
+const countFormat = new Intl.NumberFormat("en-US");
+export function formatCount(value) {
+    return countFormat.format(value);
+}
+export function pluralize(count, singular, plural = `${singular}s`) {
+    return `${formatCount(count)} ${count === 1 ? singular : plural}`;
+}

package/dist/quota.d.ts

@@ -0,0 +1,8 @@
+export type QuotaStatus = "ok" | "near" | "over";
+export type QuotaAmounts = {
+    used: number;
+    included: number;
+};
+export declare const nearLimitPercent = 80;
+export declare function quotaPercent({ used, included }: QuotaAmounts): number;
+export declare function quotaStatus(quota: QuotaAmounts): QuotaStatus;

package/dist/quota.js

@@ -0,0 +1,13 @@
+export const nearLimitPercent = 80;
+export function quotaPercent({ used, included }) {
+    if (included <= 0) {
+        return used > 0 ? 100 : 0;
+    }
+    return Math.min(Math.round((used / included) * 100), 100);
+}
+export function quotaStatus(quota) {
+    if (quota.used > quota.included) {
+        return "over";
+    }
+    return quotaPercent(quota) >= nearLimitPercent ? "near" : "ok";
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@locusgraph/utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Formatting and quota helpers LocusGraph apps share: money in cents and micro-USD, counts, dates and usage status.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/locusgraph/design.git",
+    "directory": "packages/utils"
+  },
+  "homepage": "https://design.locusgraph.com",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@locusgraph/config": "0.1.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/esm-extensions.mjs dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }