@seta-labs/geo 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @seta-labs/geo
 
+## 0.8.0
+
+- **Breaking:** `LookupCache` becomes `CachePolicy`, the cache options every
+  Seta service and SDK shares: `refresh` is now `noCache`, like the header
+  directive; `noStore`, `maxAge` and `onlyIfCached` keep their names. The type
+  and its header writer come from `@seta-labs/nestjs-cache-control/policy`,
+  bundled into the SDK: nothing more to install.
+- Each client paces its calls (`pacing`): at most 10 in flight, a `429` or
+  `503` sent again up to 4 times after its `Retry-After` (up to a minute;
+  1-8 s backoff without it), the whole queue waiting meanwhile. `pacing:
+{ concurrency, retries }` tunes it, `pacing: false` turns it off; two queues
+  are two clients.
+- `timeoutMs` (default 30 s) bounds each attempt, not the wait in the queue.
+- `ApiError.code`: Geo's error code (`CADASTRE_BLOCKED`, `NOT_CACHED`, ...)
+  read from the body.
+
 ## 0.7.0
 
 - `reverseGeocode(input)` answers from a chain of sources: the ANNCSU register

package/README.md

@@ -40,9 +40,20 @@ Do not use `$fetch` as `fetch`: it returns the parsed body instead of a Response
 
 All calls return `Promise<T>` and accept optional `{ signal }` as the last
 argument. An optional `fetch: (request: Request) => Promise<Response>` allows
-consumer-owned instrumentation or transport adapters. There is no scheduler,
-queue, rate limiter or automatic retry, including for failed writes. Consumers
-retain their own concurrency and retry policy.
+consumer-owned instrumentation or transport adapters.
+
+Each client paces its calls: at most 10 in flight, and a `429` or `503` that
+says when to come back (`Retry-After` up to a minute; 1 s, 2 s, 4 s, 8 s
+without it) is sent again up to 4 times while the client's whole queue waits.
+A refusal asking for a longer wait, every other status and network errors
+reach the caller after one attempt. Each attempt has `timeoutMs` (default
+30 s), not counting the wait in the queue. Two queues are two clients:
+
+```ts
+const geo = createGeoClient({ baseUrl, apiKey }); // lookups, territory
+const cadastre = createGeoClient({ baseUrl, apiKey, pacing: { concurrency: 4 } }); // the map, apart
+const panel = createGeoClient({ baseUrl: '/api', pacing: false }); // every call at once, once
+```
 
 | Method                                   | Input                                  |
 | ---------------------------------------- | -------------------------------------- |
@@ -66,14 +77,24 @@ validation of received data. `include` may be omitted and defaults to `best`
 on the service.
 
 The four lookups (`geocode`, `geocodeBatch`, `reverseGeocode`,
-`cadastreParcel`) take `cache` in their options, sent as `Cache-Control`:
-`{ refresh: true }` asks the provider again and stores the new answer,
-`{ refresh: true, noStore: true }` bypasses the store entirely, `{ maxAge }`
-asks again past that many seconds, `{ onlyIfCached: true }` never asks the
-provider (504 `NOT_CACHED`, or `status: 'NOT_CACHED'` for a batch item).
+`cadastreParcel`) take `cache` in their options: a `CachePolicy`, the shape
+every Seta service and SDK shares (`@seta-labs/nestjs-cache-control/policy`,
+bundled here), sent as `Cache-Control`. `{ noCache: true }` asks the provider
+again and stores the new answer, `{ noCache: true, noStore: true }` bypasses
+the store entirely, `{ maxAge }` asks again past that many seconds,
+`{ onlyIfCached: true }` never asks the provider (504 `NOT_CACHED`, or
+`status: 'NOT_CACHED'` for a batch item). Without `cache` the store answers
+when it can and the provider otherwise. The other calls read Geo's own data
+and take only `signal`.
+
+```ts
+await geo.reverseGeocode({ lat, lng }, { cache: { onlyIfCached: true } });
+await geo.reverseGeocode({ lat, lng }, { cache: jobCachePolicy() }); // the job's, at each call
+```
 
 HTTP errors are `ApiError`; their body is JSON when parseable, otherwise text,
-or `undefined` for an empty response. A `503` from `cadastreParcel` with
+or `undefined` for an empty response, and `code` is Geo's error code when the
+body has one. A `503` from `cadastreParcel` with
 `code: 'CADASTRE_BLOCKED'` means the cadastral map is refusing calls: its
 `Retry-After` header (and `retryAfterSeconds` in the body) says when to ask
 again. Network failures, aborts and JSON parsing

package/dist/index.d.ts

@@ -4,6 +4,8 @@ declare class ApiError extends Error {
     readonly status: number;
     readonly headers: Headers;
     readonly requestId: string | undefined;
+    /** Geo's error `code` (`CADASTRE_BLOCKED`, `NOT_CACHED`, ...), when the body has one. */
+    readonly code: string | undefined;
     constructor(response: Response, body: unknown);
 }
 
@@ -1294,6 +1296,31 @@ type TerritoryQuotazione = ApiSchemas['TerritoryQuotazioneDto'];
 type TerritoryCompravenditePage = ApiSchemas['TerritoryCompravenditePageDto'];
 type TerritoryCompravendita = ApiSchemas['TerritoryCompravenditaDto'];
 
+/**
+ * The request directives of RFC 9111 a lookup honours; any other directive is
+ * ignored. One shape for both sides: the server reads it from the header
+ * (`parseCacheControl`, every flag set), a client writes it
+ * (`formatCacheControl`, an absent flag is false).
+ */
+interface CachePolicy {
+    /** `no-cache`: never answer from the store without asking the provider. */
+    noCache?: boolean;
+    /** `no-store`: never write the provider's answer to the store. */
+    noStore?: boolean;
+    /** `only-if-cached`: never ask the provider; without a usable row, refuse. */
+    onlyIfCached?: boolean;
+    /** `max-age=N`: a stored row older than N seconds is not usable. */
+    maxAge?: number;
+}
+
+/** How a client paces its calls to Geo; each client has its own queue. */
+interface PacingOptions {
+    /** Requests in flight at once; default 10. */
+    concurrency?: number;
+    /** New attempts after a 429 or 503 that says when to come back; default 4 (5 attempts in all). */
+    retries?: number;
+}
+
 type TerritoryComuniQuery = NonNullable<ApiPaths['/territory/comuni']['get']['parameters']['query']>;
 type TerritoryQuotazioniQuery = NonNullable<ApiPaths['/territory/quotazioni']['get']['parameters']['query']>;
 type TerritoryCompravenditeQuery = NonNullable<ApiPaths['/territory/compravendite']['get']['parameters']['query']>;
@@ -1302,21 +1329,12 @@ interface RequestOptions {
     signal?: AbortSignal;
 }
 /**
- * How a lookup may use seta-geo's store, sent as `Cache-Control` (RFC 9111).
- * Without it the store answers when it can and the provider otherwise.
+ * The options of a lookup, the four calls Geo answers from its store:
+ * `cache` is sent as `Cache-Control` (RFC 9111). Without it Geo answers
+ * from the store when it can and asks the provider otherwise.
  */
-interface LookupCache {
-    /** `no-cache`: ask the provider even with a stored answer, and store the new one. */
-    refresh?: boolean;
-    /** `no-store`: never write the provider's answer (with `refresh`: a pure bypass). */
-    noStore?: boolean;
-    /** `max-age`: a stored answer older than this many seconds is asked again. */
-    maxAge?: number;
-    /** `only-if-cached`: never ask the provider; 504 `NOT_CACHED` without a stored answer. */
-    onlyIfCached?: boolean;
-}
 interface LookupOptions extends RequestOptions {
-    cache?: LookupCache;
+    cache?: CachePolicy;
 }
 interface GeoClientOptions {
     /** Complete API root, including /api. Relative roots are supported in browsers. */
@@ -1325,6 +1343,10 @@ interface GeoClientOptions {
     apiKey?: string;
     /** A real Fetch implementation returning a Response, not a parsed-body $fetch. */
     fetch?: (request: Request) => Promise<Response>;
+    /** Each attempt's deadline, not counting the wait in the queue; default 30 s. */
+    timeoutMs?: number;
+    /** The client's queue and its retries on 429/503; `false` sends every call at once, once. */
+    pacing?: false | PacingOptions;
 }
 interface TerritoryClient {
     status(options?: RequestOptions): Promise<TerritoryStatus>;
@@ -1350,4 +1372,4 @@ interface GeoClient {
 declare function createGeoClient(options: GeoClientOptions): GeoClient;
 
 export { ApiError, createGeoClient };
-export type { CadastreParcelRequest, CadastreParcelResult, CadastreParcelRow, CadastreParcelsPage, CadastreParcelsQuery, GeoAdminArea, GeoClient, GeoClientOptions, GeoStreetMatch, GeocodeBatchRequest, GeocodeBatchResponse, GeocodeRequest, GeocodeResult, LookupCache, LookupOptions, RequestOptions, ReverseGeocodeRequest, ReverseGeocodeResult, TerritoryClient, TerritoryCompravendita, TerritoryCompravenditePage, TerritoryCompravenditeQuery, TerritoryComune, TerritoryComuneDetail, TerritoryComuneRiga, TerritoryComuniPage, TerritoryComuniQuery, TerritoryDatasets, TerritoryOmi, TerritoryPointResult, TerritoryQuotazione, TerritoryQuotazioniPage, TerritoryQuotazioniQuery, TerritoryResolveRequest, TerritoryResolveResponse, TerritoryStatus, TerritoryTerritorio };
+export type { CachePolicy, CadastreParcelRequest, CadastreParcelResult, CadastreParcelRow, CadastreParcelsPage, CadastreParcelsQuery, GeoAdminArea, GeoClient, GeoClientOptions, GeoStreetMatch, GeocodeBatchRequest, GeocodeBatchResponse, GeocodeRequest, GeocodeResult, LookupOptions, PacingOptions, RequestOptions, ReverseGeocodeRequest, ReverseGeocodeResult, TerritoryClient, TerritoryCompravendita, TerritoryCompravenditePage, TerritoryCompravenditeQuery, TerritoryComune, TerritoryComuneDetail, TerritoryComuneRiga, TerritoryComuniPage, TerritoryComuniQuery, TerritoryDatasets, TerritoryOmi, TerritoryPointResult, TerritoryQuotazione, TerritoryQuotazioniPage, TerritoryQuotazioniQuery, TerritoryResolveRequest, TerritoryResolveResponse, TerritoryStatus, TerritoryTerritorio };

package/dist/index.js

@@ -7,11 +7,14 @@ var ApiError = class extends Error {
     this.status = response.status;
     this.headers = new Headers(response.headers);
     this.requestId = response.headers.get("x-request-id") ?? void 0;
+    this.code = codeOf(body);
   }
   body;
   status;
   headers;
   requestId;
+  /** Geo's error `code` (`CADASTRE_BLOCKED`, `NOT_CACHED`, ...), when the body has one. */
+  code;
 };
 async function readErrorBody(response) {
   const text = await response.text();
@@ -22,9 +25,126 @@ async function readErrorBody(response) {
     return text;
   }
 }
+function codeOf(body) {
+  if (typeof body !== "object" || body === null || !("code" in body)) return void 0;
+  return typeof body.code === "string" ? body.code : void 0;
+}
+
+// ../../node_modules/.pnpm/@seta-labs+nestjs-cache-control@0.2.1_@nestjs+common@12.1.2_class-transformer@0.5.1_cla_d70e55208c987ac6b22f0eff0ce5869e/node_modules/@seta-labs/nestjs-cache-control/dist/cache-policy.util.js
+var MAX_DELTA_SECONDS = 2147483648;
+function formatCacheControl(policy) {
+  if (!policy)
+    return void 0;
+  const maxAge = policy.maxAge;
+  const directives = [
+    policy.noCache ? "no-cache" : void 0,
+    policy.noStore ? "no-store" : void 0,
+    maxAge !== void 0 && Number.isFinite(maxAge) ? `max-age=${Math.min(Math.max(0, Math.floor(maxAge)), MAX_DELTA_SECONDS)}` : void 0,
+    policy.onlyIfCached ? "only-if-cached" : void 0
+  ].filter((directive) => directive !== void 0);
+  return directives.length > 0 ? directives.join(", ") : void 0;
+}
 
 // src/client.ts
 import createClient from "openapi-fetch";
+
+// src/pacing.ts
+var DEFAULT_CONCURRENCY = 10;
+var DEFAULT_RETRIES = 4;
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 503]);
+var BACKOFF_MS = 1e3;
+var MAX_WAIT_MS = 6e4;
+function pacedFetch(fetch, options = {}) {
+  const run = limiter(options.concurrency ?? DEFAULT_CONCURRENCY);
+  const retries = options.retries ?? DEFAULT_RETRIES;
+  let pausedUntil = 0;
+  const send = async (request, attempt) => {
+    while (pausedUntil > Date.now()) await sleepUntil(pausedUntil, request.signal);
+    const response = await fetch(request.clone());
+    const waitMs = attempt < retries ? retryDelay(response, attempt) : void 0;
+    if (waitMs !== void 0) pausedUntil = Math.max(pausedUntil, Date.now() + waitMs);
+    return { response, waitMs };
+  };
+  return async (request) => {
+    for (let attempt = 0; ; attempt++) {
+      const { response, waitMs } = await run(request.signal, () => send(request, attempt));
+      if (waitMs === void 0) return response;
+      await response.body?.cancel();
+    }
+  };
+}
+function timedFetch(fetch, timeoutMs) {
+  return (request) => fetch(
+    new Request(request, {
+      signal: AbortSignal.any([request.signal, AbortSignal.timeout(timeoutMs)])
+    })
+  );
+}
+function retryDelay(response, attempt) {
+  if (!RETRY_STATUSES.has(response.status)) return void 0;
+  const header = response.headers.get("retry-after");
+  const waitMs = header === null ? BACKOFF_MS * 2 ** attempt : retryAfterMs(header);
+  return waitMs !== void 0 && waitMs <= MAX_WAIT_MS ? waitMs : void 0;
+}
+function retryAfterMs(header) {
+  const value = header.trim();
+  if (/^\d+$/.test(value)) return Number(value) * 1e3;
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+}
+function limiter(concurrency) {
+  let active = 0;
+  const waiting = [];
+  const acquire = (signal) => {
+    signal.throwIfAborted();
+    if (active < concurrency) {
+      active++;
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      const start = () => {
+        signal.removeEventListener("abort", abort);
+        active++;
+        resolve();
+      };
+      const abort = () => {
+        waiting.splice(waiting.indexOf(start), 1);
+        reject(signal.reason);
+      };
+      waiting.push(start);
+      signal.addEventListener("abort", abort, { once: true });
+    });
+  };
+  return async (signal, task) => {
+    await acquire(signal);
+    try {
+      return await task();
+    } finally {
+      active--;
+      waiting.shift()?.();
+    }
+  };
+}
+function sleepUntil(time, signal) {
+  const delay = time - Date.now();
+  if (delay <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    signal.throwIfAborted();
+    const timer = setTimeout(done, delay);
+    signal.addEventListener("abort", abort, { once: true });
+    function done() {
+      signal.removeEventListener("abort", abort);
+      resolve();
+    }
+    function abort() {
+      clearTimeout(timer);
+      reject(signal.reason);
+    }
+  });
+}
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
 function apiBaseUrl(baseUrl) {
   const url = new URL(baseUrl, globalThis.location?.href);
   if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
@@ -39,19 +159,9 @@ async function data(request) {
   if (result.data === void 0) throw new SyntaxError("Geo API returned an empty JSON response");
   return result.data;
 }
-function cacheControl(cache) {
-  if (!cache) return void 0;
-  const directives = [
-    cache.refresh ? "no-cache" : void 0,
-    cache.noStore ? "no-store" : void 0,
-    cache.maxAge === void 0 ? void 0 : `max-age=${Math.max(0, Math.floor(cache.maxAge))}`,
-    cache.onlyIfCached ? "only-if-cached" : void 0
-  ].filter((directive) => directive !== void 0);
-  return directives.length > 0 ? directives.join(", ") : void 0;
-}
 function lookupInit(options) {
   const { cache, ...request } = options ?? {};
-  const header = cacheControl(cache);
+  const header = formatCacheControl(cache);
   return header ? { ...request, headers: { "cache-control": header } } : request;
 }
 function territory(client) {
@@ -73,7 +183,7 @@ function territory(client) {
 function createGeoClient(options) {
   const client = createClient({
     baseUrl: apiBaseUrl(options.baseUrl),
-    fetch: options.fetch,
+    fetch: transport(options),
     headers: options.apiKey ? { "x-api-key": options.apiKey } : void 0
   });
   client.use({
@@ -90,6 +200,11 @@ function createGeoClient(options) {
     territory: territory(client)
   };
 }
+function transport(options) {
+  const send = options.fetch ?? ((request) => globalThis.fetch(request));
+  const timed = timedFetch(send, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  return options.pacing === false ? timed : pacedFetch(timed, options.pacing);
+}
 export {
   ApiError,
   createGeoClient

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@seta-labs/geo",
-    "version": "0.7.0",
+    "version": "0.8.0",
     "description": "Typed Fetch client for the Seta Geo HTTP API",
     "license": "UNLICENSED",
     "type": "module",
@@ -44,6 +44,7 @@
     "devDependencies": {
         "@seta-geo/types": "workspace:*",
         "@seta-labs/config": "^0.16.1",
+        "@seta-labs/nestjs-cache-control": "0.2.1",
         "tsup": "^9.0.0",
         "typescript": "^6.0.3",
         "vitest": "^5.0.3"