@simpleapps-com/augur-utils 2026.11.2 → 2026.11.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/rules.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { Millis } from "./duration";
1
2
  /** An invoice's payment status, from its flag and amounts. */
2
3
  export type PaymentStatus = "Paid" | "Partially Paid" | "Unpaid";
3
4
  /**
@@ -42,4 +43,35 @@ export declare function takerOf(taker: string | undefined): string;
42
43
  * @ensures exactly the model's AddressDifferent
43
44
  */
44
45
  export declare function addressDifferentOf(line1Same: boolean, citySame: boolean, stateSame: boolean, zipSame: boolean): boolean;
46
+ /**
47
+ * The gcTime a query gets: none on the server (`null`, which the caller turns into `Infinity`,
48
+ * so query-core schedules no GC timer and a per-request cache is freed with the request), the
49
+ * client's value in the browser. Moved from augur-core (#94) so the CACHE_CONFIG tiers use it.
50
+ *
51
+ * @ensures exactly the model's GcTime
52
+ */
53
+ export declare function gcTimeFor(isServer: boolean, clientGcTime: Millis): Millis | null;
54
+ /** A CACHE_CONFIG tier's name. */
55
+ export type TierName = "STATIC" | "SEMI_STATIC" | "DYNAMIC" | "CART" | "REALTIME";
56
+ /**
57
+ * A tier's staleTime: STATIC 1 h, SEMI_STATIC 10 min, DYNAMIC 5 min, CART 2 min, REALTIME 0.
58
+ *
59
+ * @ensures exactly the model's TierStaleTime
60
+ */
61
+ export declare function tierStaleTime(t: TierName): Millis;
62
+ /**
63
+ * A tier's gcTime in the browser: STATIC 24 h, SEMI_STATIC 4 h, DYNAMIC and CART 30 min,
64
+ * REALTIME 5 min; never shorter than its staleTime. On the server the tier's gcTime is
65
+ * `gcTimeFor(true, …)`: none.
66
+ *
67
+ * @ensures exactly the model's TierBrowserGcTime; result ≥ tierStaleTime(t)
68
+ */
69
+ export declare function tierBrowserGcTime(t: TierName): Millis;
70
+ /**
71
+ * Outside a browser (Node SSR, edge, Deno): no `window`, or Deno (which has one). Mirrors
72
+ * query-core's `isServer`; runtime.ts reads the two facts per call.
73
+ *
74
+ * @ensures exactly the model's ServerRuntime
75
+ */
76
+ export declare function serverRuntimeOf(hasWindow: boolean, hasDeno: boolean): boolean;
45
77
  //# sourceMappingURL=rules.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAMA,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,gBAAgB,GAAG,QAAQ,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,MAAM,GACjB,aAAa,CAQf;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAIzE;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAO9D;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAIzD;AAED,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK/D;AAED,2BAA2B;AAC3B,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAkBhE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC;AAElE,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,GAAG,YAAY,CAQxF;AAED,oDAAoD;AACpD,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKzD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,OAAO,EAClB,QAAQ,EAAE,OAAO,EACjB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,OAAO,GACf,OAAO,CAIT"}
1
+ {"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,gBAAgB,GAAG,QAAQ,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,OAAO,EACnB,UAAU,EAAE,MAAM,GACjB,aAAa,CAQf;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAIzE;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAO9D;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAIzD;AAED,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK/D;AAED,2BAA2B;AAC3B,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAkBhE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC;AAElE,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,GAAG,YAAY,CAQxF;AAED,oDAAoD;AACpD,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKzD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,OAAO,EAClB,QAAQ,EAAE,OAAO,EACjB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,OAAO,GACf,OAAO,CAIT;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKhF;AAED,kCAAkC;AAClC,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAElF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAYjD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAYrD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAI7E"}
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Which runtime a query is built in, and the gcTime it gets there. The decision is the proved
3
+ * `gcTimeFor` (rules.ts, model `AugurUtils.GcTime`); this file only reads the runtime. Moved
4
+ * from augur-core (#94, 2026-11-07), which re-exports both, so the CACHE_CONFIG tiers can use
5
+ * them: augur-core depends on augur-utils, never the other way.
6
+ */
7
+ import type { Millis } from "./duration";
8
+ /**
9
+ * Returns true when running outside a browser (Node SSR, edge, Deno).
10
+ * Mirrors `isServer` in `@tanstack/query-core` (`build/modern/utils.js`).
11
+ * Evaluated per call, not at module scope, so `"use client"` modules that
12
+ * also run during SSR resolve correctly on each pass.
13
+ */
14
+ export declare function isServerRuntime(): boolean;
15
+ /**
16
+ * Returns the React Query `gcTime` to use for a query built in this runtime.
17
+ * On the server returns `Infinity`, which query-core treats as "schedule no
18
+ * GC timer", so a per-request QueryClient is freed when the request ends.
19
+ * A finite value would start a timer that pins the whole request cache.
20
+ * In the browser returns `clientGcTime` unchanged. The result is a `number`, not `Millis`:
21
+ * `Infinity` is no whole number of milliseconds.
22
+ */
23
+ export declare function resolveGcTime(clientGcTime: Millis): number;
24
+ //# sourceMappingURL=runtime.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAIzC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE1D"}
package/llms.txt CHANGED
@@ -23,6 +23,7 @@ The docs are at https://augur.build/docs/packages (the API reference lists every
23
23
 
24
24
  ## @simpleapps-com/augur-utils
25
25
 
26
+ - const: addMillis - A clock reading plus a duration, both milliseconds: when something expires.
26
27
  - const: BillingAddressInvoiceSchema - Valibot schema for billing address with required PO number (invoice payments).
27
28
  - const: BillingAddressSchema - Valibot schema for billing address validation. Less strict than shipping: allows PO Box, no email/phone required.
28
29
  - const: BLUR_DATA_URL - 1x1 transparent PNG for Next.js `<Image blurDataURL={...}>` placeholders.
@@ -36,8 +37,10 @@ The docs are at https://augur.build/docs/packages (the API reference lists every
36
37
  - function: cn - Merge Tailwind classes without conflicts. Web only (tailwind-merge is meaningless in RN).
37
38
  - const: CONTIGUOUS_STATES - Lower 48 contiguous states.
38
39
  - function: createImageConfig - Creates a frozen ImageConfig object.
40
+ - const: days - `n` days, in seconds.
39
41
  - function: derivePrice - Pure price derivation — usable in hooks AND server components.
40
42
  - const: faqLd - A FAQ page's FAQPage markup as text: one Question per entry.
43
+ - const: floorSeconds - Milliseconds as whole seconds, rounded down.
41
44
  - function: formatPrice - Locale-aware currency formatting. Defaults to USD -- consumers can override locale and currency.
42
45
  - function: generateBreadcrumbJsonLd - Generates a Schema.org BreadcrumbList JSON-LD object from an array of breadcrumb items.
43
46
  - function: generateProductJsonLd - Generates a Schema.org Product JSON-LD string from an inventory document. Returns null if the item is suppressed, unnamed, or has no price.
@@ -49,19 +52,31 @@ The docs are at https://augur.build/docs/packages (the API reference lists every
49
52
  - function: getSchemaAvailability - Maps resolved stock to a Schema.org availability URL.
50
53
  - function: getShippingLeadDate - Get shipping lead date estimate based on days string (the table is `shippingLeadOf`).
51
54
  - function: hasPriceBreaks - Type guard: true when `libraryPriceData` is the price-page shape with quantity `breaks`.
55
+ - const: hours - `n` hours, in seconds.
52
56
  - const: idRef - A reference to another node by its @id, as JSON text.
53
57
  - function: isAddressDifferent - Compares a user-entered address with a SmartyStreets-validated address. Returns true if any field differs (case-insensitive for address/city, exact match for state abbreviation and zip code).
58
+ - function: isServerRuntime - Returns true when running outside a browser (Node SSR, edge, Deno). Mirrors `isServer` in `@tanstack/query-core` (`build/modern/utils.js`). Evaluated per call, not at module scope, so `"use client"` modules that also run during SSR resolve correctly on each pass.
59
+ - const: millis - `n` milliseconds, for a duration under a second.
60
+ - const: millisOf - `n` as `Millis`, or null unless it is a safe integer at least 0.
61
+ - const: minusMillis - A reading less a duration, never below 0.
62
+ - const: minutes - `n` minutes, in seconds.
54
63
  - const: nodeHead - The schema.org context and a node's type: its first two members, as JSON text.
55
64
  - function: normalizePath - Normalizes an image path by: 1. Returning it as-is if it starts with `http` (external URL). 2. Stripping configured prefixes (defaults: `/images`, `images`). 3. Prepending `defaultPath` for bare filenames (no `/`). 4. Stripping leading slashes.
56
65
  - function: paginateOffset - Returns a copy of filters with offset adjusted for the given page.
57
66
  - function: pushTrackingData - Push ecommerce tracking data to window.dataLayer using the GA4 clear-then-push pattern.
67
+ - function: resolveGcTime - Returns the React Query `gcTime` to use for a query built in this runtime. On the server returns `Infinity`, which query-core treats as "schedule no GC timer", so a per-request QueryClient is freed when the request ends. A finite value would start a timer that pins the whole request cache. In the browser returns `clientGcTime` unchanged. The result is a `number`, not `Millis`: `Infinity` is no whole number of milliseconds.
58
68
  - function: resolveStock - Pure stock resolution -- usable in hooks AND server components.
59
69
  - function: roundHalfAway - Round half away from zero to `decimals` places.
60
70
  - function: sanitizeHtmlImages - Rewrites `<img src="...">` attributes in an HTML string to use agr.media URLs. Useful for CMS/Joomla content that contains raw image references.
71
+ - const: seconds - `n` seconds.
72
+ - const: secondsOf - `n` as `Seconds`, or null unless it is a safe integer at least 0.
61
73
  - function: serializeCategoryFilters - Converts TItemsFilters to the SDK params shape for category item endpoints.
62
74
  - function: serializeSearchParams - Converts TItemsFilters to the SDK params shape for search endpoints.
63
75
  - function: serializeTransforms - Serializes transform options into the CDN path segment. Example: `{ width: 400, format: "webp" }` → `"w_400,f_webp"`
64
76
  - const: ShippingAddressSchema - Valibot schema for shipping address validation. Enforces no PO Box, requires street number, formats phone number.
77
+ - function: tierBrowserGcTime - A tier's gcTime in the browser: STATIC 24 h, SEMI_STATIC 4 h, DYNAMIC and CART 30 min, REALTIME 5 min; never shorter than its staleTime. On the server the tier's gcTime is `gcTimeFor(true, …)`: none.
78
+ - function: tierStaleTime - A tier's staleTime: STATIC 1 h, SEMI_STATIC 10 min, DYNAMIC 5 min, CART 2 min, REALTIME 0.
79
+ - const: toMillis - Seconds as milliseconds, exactly.
65
80
  - function: trackAddToCart - Track add_to_cart event to Google Analytics dataLayer.
66
81
  - function: trackViewItem - Track view_item event to Google Analytics dataLayer.
67
82
  - function: transformShipToAddress - Normalizes a raw ship-to address object (camelCase or snake_case, physical or mailing) into a consistent ShipToAddress shape.
@@ -71,6 +86,7 @@ The docs are at https://augur.build/docs/packages (the API reference lists every
71
86
  - const: US_STATES_FULL - All US states and territories — full data from states-us.
72
87
  - const: US_TERRITORIES - US territories (PR, GU, VI, AS, MP).
73
88
  - const: VALIDATION_PATTERNS - Common regex patterns used for form validation across augur-hosted sites.
89
+ - const: wholeSeconds - An outside count of seconds, rounded down; 0 when it is then no safe integer at least 0.
74
90
  - type: AddToCartEventParams
75
91
  - type: BillingAddress
76
92
  - type: BreadcrumbJsonLdItem
@@ -87,6 +103,7 @@ The docs are at https://augur.build/docs/packages (the API reference lists every
87
103
  - type: ImageTransforms
88
104
  - type: ImageUrlOptions
89
105
  - type: MenuItem
106
+ - type: Millis
90
107
  - type: OeHdr
91
108
  - type: OeLine
92
109
  - type: OrderHeader
@@ -103,6 +120,7 @@ The docs are at https://augur.build/docs/packages (the API reference lists every
103
120
  - type: SafeActionResult
104
121
  - type: SchemaAvailability
105
122
  - type: SearchParamOptions
123
+ - type: Seconds
106
124
  - type: ShippingAddress
107
125
  - type: ShipToAddress
108
126
  - type: TAccountQuery
@@ -118,6 +136,7 @@ The docs are at https://augur.build/docs/packages (the API reference lists every
118
136
  - type: TCategoryChild
119
137
  - type: TCategoryItemsResult
120
138
  - type: TCheckoutResult
139
+ - type: TierName
121
140
  - type: TInventorySupplier
122
141
  - type: TInvMast
123
142
  - type: TInvMastDoc
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simpleapps-com/augur-utils",
3
- "version": "2026.11.2",
3
+ "version": "2026.11.3",
4
4
  "description": "Shared types, cache configuration, and utility functions for Augur ecommerce sites",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -62,9 +62,10 @@
62
62
  "@atlas/eslint-config": "0.0.0",
63
63
  "@atlas/tsconfig": "0.0.0",
64
64
  "@atlas/tsup-config": "0.0.0",
65
+ "@atlas/foundation": "0.0.0",
65
66
  "@atlas/utils": "0.0.0",
66
67
  "@atlas/vitest-config": "0.0.0",
67
- "@simpleapps-com/augur-api": "2026.11.2"
68
+ "@simpleapps-com/augur-api": "2026.11.3"
68
69
  },
69
70
  "engines": {
70
71
  "node": ">=22.0.0"
@@ -72,7 +73,7 @@
72
73
  "scripts": {
73
74
  "build": "tsup && tsc -p tsconfig.build.json",
74
75
  "lint": "eslint .",
75
- "proofs": "lsc check --backend=dafny",
76
+ "proofs": "lsc gen-check --backend=dafny && node ../../models/lsc-check.mjs",
76
77
  "test": "vitest run --coverage",
77
78
  "typecheck": "tsc --noEmit"
78
79
  }