@seta-labs/geo 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @seta-labs/geo
 
+## 0.3.0
+
+- `geocode`, `geocodeBatch`, `reverseGeocode` and `cadastreParcel` take
+  `cache: { refresh, noStore, maxAge, onlyIfCached }`, sent as
+  `Cache-Control` (`no-cache`, `no-store`, `max-age`, `only-if-cached`).
+  Without it nothing changes. New types `LookupCache` and `LookupOptions`.
+- A lookup refused by `onlyIfCached` rejects with `ApiError` 504
+  (`code: 'NOT_CACHED'`); a batch item has `status: 'NOT_CACHED'`.
+
 ## 0.2.0
 
 - New `cadastreParcel({ lat, lng })` on `POST /cadastre/parcel`: what the AdE

package/README.md

@@ -64,6 +64,13 @@ OpenAPI remains authoritative: TypeScript provides static types, not runtime
 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).
+
 HTTP errors are `ApiError`; their body is JSON when parseable, otherwise text,
 or `undefined` for an empty response. A `503` from `cadastreParcel` with
 `code: 'CADASTRE_BLOCKED'` means the cadastral map is refusing calls: its

package/dist/index.d.ts

@@ -355,8 +355,11 @@ interface components {
             include?: 'best' | 'full';
         };
         GeocodeResultDto: {
-            /** @enum {string} */
-            status: 'OK' | 'NO_RESULT' | 'INVALID_QUERY';
+            /**
+             * @description NOT_CACHED: a batch item refused by Cache-Control only-if-cached.
+             * @enum {string}
+             */
+            status: 'OK' | 'NO_RESULT' | 'INVALID_QUERY' | 'NOT_CACHED';
             /** @description The normalized query actually used as cache key and provider input. */
             query: string | null;
             lat: number | null;
@@ -652,7 +655,10 @@ interface operations {
     GeocodeController_geocode: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description no-cache: ask the provider and store its answer; no-store: never write the store; max-age=N: a stored answer older than N seconds is asked again; only-if-cached: never ask the provider. The response says what happened in Cache-Status (hit, fwd=miss|request|stale, stored) and, on a hit, Age. */
+                'Cache-Control'?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -684,12 +690,22 @@ interface operations {
                 };
                 content?: never;
             };
+            /** @description NOT_CACHED: only-if-cached and no usable stored answer. */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     GeocodeController_geocodeBatch: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description Applies to every item: no-cache, no-store, max-age=N, only-if-cached. An item only-if-cached refuses has status NOT_CACHED; the batch still answers 200. */
+                'Cache-Control'?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -726,7 +742,10 @@ interface operations {
     GeocodeController_reverseGeocode: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description no-cache: ask the provider and store its answer; no-store: never write the store; max-age=N: a stored answer older than N seconds is asked again; only-if-cached: never ask the provider. The response says what happened in Cache-Status (hit, fwd=miss|request|stale, stored) and, on a hit, Age. */
+                'Cache-Control'?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -758,12 +777,22 @@ interface operations {
                 };
                 content?: never;
             };
+            /** @description NOT_CACHED: only-if-cached and no usable stored answer. */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     CadastreController_parcel: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description no-cache: ask the provider and store its answer; no-store: never write the store; max-age=N: a stored answer older than N seconds is asked again; only-if-cached: never ask the provider. The response says what happened in Cache-Status (hit, fwd=miss|request|stale, stored) and, on a hit, Age. */
+                'Cache-Control'?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -803,6 +832,13 @@ interface operations {
                 };
                 content?: never;
             };
+            /** @description NOT_CACHED: only-if-cached and no usable stored answer. */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     TerritoryController_status: {
@@ -1065,6 +1101,23 @@ type TerritoryCompravenditeQuery = NonNullable<ApiPaths['/territory/compravendit
 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.
+ */
+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;
+}
 interface GeoClientOptions {
     /** Complete API root, including /api. Relative roots are supported in browsers. */
     baseUrl: string;
@@ -1083,15 +1136,16 @@ interface TerritoryClient {
     resolve(input: TerritoryResolveRequest, options?: RequestOptions): Promise<TerritoryResolveResponse>;
 }
 interface GeoClient {
-    geocode(input: GeocodeRequest, options?: RequestOptions): Promise<GeocodeResult>;
-    geocodeBatch(input: GeocodeBatchRequest, options?: RequestOptions): Promise<GeocodeBatchResponse>;
-    reverseGeocode(input: ReverseGeocodeRequest, options?: RequestOptions): Promise<ReverseGeocodeResult>;
+    geocode(input: GeocodeRequest, options?: LookupOptions): Promise<GeocodeResult>;
+    /** `cache` applies to every item; an item only-if-cached refuses has status NOT_CACHED. */
+    geocodeBatch(input: GeocodeBatchRequest, options?: LookupOptions): Promise<GeocodeBatchResponse>;
+    reverseGeocode(input: ReverseGeocodeRequest, options?: LookupOptions): Promise<ReverseGeocodeResult>;
     /** What the AdE cadastral map finds under a point; 503 `CADASTRE_BLOCKED` carries Retry-After. */
-    cadastreParcel(input: CadastreParcelRequest, options?: RequestOptions): Promise<CadastreParcelResult>;
+    cadastreParcel(input: CadastreParcelRequest, options?: LookupOptions): Promise<CadastreParcelResult>;
     territory: TerritoryClient;
 }
 
 declare function createGeoClient(options: GeoClientOptions): GeoClient;
 
 export { ApiError, createGeoClient };
-export type { CadastreParcelRequest, CadastreParcelResult, GeoClient, GeoClientOptions, GeocodeBatchRequest, GeocodeBatchResponse, GeocodeRequest, GeocodeResult, RequestOptions, ReverseGeocodeRequest, ReverseGeocodeResult, TerritoryClient, TerritoryCompravendita, TerritoryCompravenditePage, TerritoryCompravenditeQuery, TerritoryComune, TerritoryComuneDetail, TerritoryComuneRiga, TerritoryComuniPage, TerritoryComuniQuery, TerritoryDatasets, TerritoryOmi, TerritoryPointResult, TerritoryQuotazione, TerritoryQuotazioniPage, TerritoryQuotazioniQuery, TerritoryResolveRequest, TerritoryResolveResponse, TerritoryStatus };
+export type { CadastreParcelRequest, CadastreParcelResult, GeoClient, GeoClientOptions, 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 };

package/dist/index.js

@@ -39,6 +39,21 @@ 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);
+  return header ? { ...request, headers: { "cache-control": header } } : request;
+}
 function territory(client) {
   return {
     status: (options) => data(client.GET("/territory/status", { ...options })),
@@ -67,10 +82,10 @@ function createGeoClient(options) {
     }
   });
   return {
-    geocode: (input, request) => data(client.POST("/geocode", { ...request, body: input })),
-    geocodeBatch: (input, request) => data(client.POST("/geocode/batch", { ...request, body: input })),
-    reverseGeocode: (input, request) => data(client.POST("/geocode/reverse", { ...request, body: input })),
-    cadastreParcel: (input, request) => data(client.POST("/cadastre/parcel", { ...request, body: input })),
+    geocode: (input, request) => data(client.POST("/geocode", { ...lookupInit(request), body: input })),
+    geocodeBatch: (input, request) => data(client.POST("/geocode/batch", { ...lookupInit(request), body: input })),
+    reverseGeocode: (input, request) => data(client.POST("/geocode/reverse", { ...lookupInit(request), body: input })),
+    cadastreParcel: (input, request) => data(client.POST("/cadastre/parcel", { ...lookupInit(request), body: input })),
     territory: territory(client)
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@seta-labs/geo",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Typed Fetch client for the Seta Geo HTTP API",
     "license": "UNLICENSED",
     "type": "module",