bcchapi 2.0.1 → 2.2.0

package/CHANGELOG.md

@@ -6,27 +6,83 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 ---
 
-## [2.0.1] - 2026-03-10
+## [2.2.0] - 2026-03-10
+
+
+### Added
+
+- Add fillForward utility
+
 
 ### Changed
 
-- Updated README with full API reference and usage examples
-- Cleaned up CHANGELOG to start from v2.0.0
+- Always run format before check in dev workflow
+- Fix formatting
+- Add check script and move release docs to CONTRIBUTING.md
+- Update README for v2.1.0 caching and fix AGENTS.md checklists
+
 
 ---
+## [2.1.0] - 2026-03-10
 
-## [2.0.0] - 2026-03-10
 
 ### Added
 
-- `bcchapi/client` — typed HTTP client (`Client`, `ApiError`, `HttpError`) for the Banco Central de Chile REST API
-- `bcchapi/series` — curated `SERIES` constants covering exchange rates, prices, interest rates, money, national accounts, external sector, employment, public finances, and capital markets
-- `bcchapi/utils` — observation transform functions (`parseValue`, `filterValid`, `toNumbers`, `toMap`, `toArrays`, `parseObservationDate`, `formatQueryDate`) and statistics functions (`mean`, `stdDev`, `min`, `max`, `periodVariation`, `annualVariation`, `rollingMean`)
-- ESM-only output targeting Node.js >= 24
-- Full TypeScript declarations and source maps
-- npm provenance via GitHub Actions (SLSA)
+- Add pluggable caching layer to Client (bcchapi/cache)
+
+
+### Changed
+
+- Bump version to 2.1.0
+- Release v2.1.0
+- Fix formatting
+
+
+---
+## [2.0.1] - 2026-03-10
+
+
+### Changed
+
+- Release v2.0.1
+- Rewrite CHANGELOG for v2.0.0 initial release
+- Write README for bcchapi v2
+
+
+---
+## [2.0.0] - 2026-03-10
+
+
+### Changed
+
+- Rename package to bcchapi and bump to v2.0.0
+
+
+### Fixed
+
+- Update repository URLs to bcchapi after GitHub rename
+
 
 ---
+## [0.1.0] - 2026-03-10
+
+
+### Added
+
+- Wire up root src/index.ts re-exports and replace template test
+- Add date, transform, and stats utility functions
+- Add SERIES constants with curated well-known series IDs
+- Add Client, ApiError, and HttpError with full test coverage
+
+
+### Changed
+
+- Release v0.1.0
+
+
+### Fixed
+
+- Set publishConfig access to public for npm provenance
+
 
-[2.0.1]: https://github.com/airarrazaval/bcchapi/compare/v2.0.0...v2.0.1
-[2.0.0]: https://github.com/airarrazaval/bcchapi/releases/tag/v2.0.0
+---

package/README.md

@@ -31,14 +31,14 @@ const data = await client.getSeries(SERIES.PRICES.UF, {
   lastdate: '2024-12-31',
 });
 
-console.log(data.descripIng);   // "Unidad de Fomento (UF)"
+console.log(data.descripIng); // "Unidad de Fomento (UF)"
 console.log(data.observations); // [{ indexDateString, value, statusCode }, ...]
 ```
 
 ### Transform observations
 
 ```ts
-import { toNumbers, toArrays, filterValid, mean, rollingMean } from 'bcchapi/utils';
+import { toNumbers, toArrays, filterValid, fillForward, mean, rollingMean } from 'bcchapi/utils';
 
 // Parse values to number | null (null for gaps)
 const values = toNumbers(data.observations); // [37000.12, null, 37050.45, ...]
@@ -49,6 +49,11 @@ const { dates, values } = toArrays(data.observations);
 // Filter out gap observations
 const valid = filterValid(data.observations);
 
+// Fill gaps by carrying the last valid value forward (e.g. weekends, holidays)
+// Throws if the first observation has no valid value — ensure the start date
+// falls on a trading day.
+const filled = fillForward(data.observations);
+
 // Summary statistics (gaps are ignored)
 const avg = mean(data.observations);
 
@@ -72,7 +77,40 @@ const yoy = annualVariation(cpi.observations, 12);
 
 ```ts
 const monthlySeries = await client.searchSeries('MONTHLY');
-console.log(monthlySeries.map(s => s.englishTitle));
+console.log(monthlySeries.map((s) => s.englishTitle));
+```
+
+### Enable caching
+
+```ts
+import { Client } from 'bcchapi/client';
+import { MemoryCache } from 'bcchapi/cache';
+
+const client = new Client({
+  user: 'me@example.com',
+  pass: 'secret',
+  cache: new MemoryCache({ defaultTtlMs: 60 * 60 * 1000 }), // 1 hour
+});
+
+// Repeated calls with the same arguments hit the cache — no HTTP request
+const data = await client.getSeries(SERIES.PRICES.UF);
+```
+
+Bring your own backend by implementing the `Cache` interface:
+
+```ts
+import type { Cache } from 'bcchapi/cache';
+
+const redisCache: Cache = {
+  get: (key) => {
+    /* ... */
+  },
+  set: (key, value, ttlMs) => {
+    /* ... */
+  },
+};
+
+const client = new Client({ user, pass, cache: redisCache });
 ```
 
 ### Error handling
@@ -102,21 +140,23 @@ try {
 
 #### `new Client(options)`
 
-| Option | Type | Description |
-| ------ | ---- | ----------- |
-| `user` | `string` | BCCH account email |
-| `pass` | `string` | BCCH account password |
-| `fetch` | `typeof fetch` | Custom fetch implementation (optional, useful for testing) |
+| Option       | Type           | Description                                                                       |
+| ------------ | -------------- | --------------------------------------------------------------------------------- |
+| `user`       | `string`       | BCCH account email                                                                |
+| `pass`       | `string`       | BCCH account password                                                             |
+| `fetch`      | `typeof fetch` | Custom fetch implementation (optional, useful for testing)                        |
+| `cache`      | `Cache`        | Cache backend (optional) — any object satisfying the `Cache` interface            |
+| `cacheTtlMs` | `number`       | TTL in milliseconds passed to `cache.set` on every successful response (optional) |
 
 #### `client.getSeries(seriesId, options?)`
 
 Fetches observations for a single time series.
 
-| Parameter | Type | Description |
-| --------- | ---- | ----------- |
-| `seriesId` | `string` | BCCH series identifier |
+| Parameter           | Type     | Description                                                |
+| ------------------- | -------- | ---------------------------------------------------------- |
+| `seriesId`          | `string` | BCCH series identifier                                     |
 | `options.firstdate` | `string` | Start date `"YYYY-MM-DD"` (defaults to earliest available) |
-| `options.lastdate` | `string` | End date `"YYYY-MM-DD"` (defaults to most recent) |
+| `options.lastdate`  | `string` | End date `"YYYY-MM-DD"` (defaults to most recent)          |
 
 Returns `Promise<SeriesData>`.
 
@@ -126,21 +166,42 @@ Returns metadata for all series with the given frequency. `frequency` is one of
 
 Returns `Promise<SeriesInfo[]>`.
 
+### `bcchapi/cache`
+
+#### `Cache` interface
+
+Minimal interface for plugging in any cache backend:
+
+```ts
+interface Cache {
+  get(key: string): unknown;
+  set(key: string, value: unknown, ttlMs?: number): void;
+}
+```
+
+#### `new MemoryCache(options?)`
+
+Built-in in-memory cache. Entries are evicted lazily on `get` — no background timers.
+
+| Option         | Type     | Description                                                      |
+| -------------- | -------- | ---------------------------------------------------------------- |
+| `defaultTtlMs` | `number` | Default TTL in milliseconds. Omit for entries that never expire. |
+
 ### `bcchapi/series`
 
 `SERIES` is a nested `as const` object of curated series IDs grouped by domain:
 
-| Group | Description |
-| ----- | ----------- |
-| `SERIES.EXCHANGE_RATE` | USD/CLP and major currency pairs |
-| `SERIES.PRICES` | UF, UTM, IVP, CPI and components |
-| `SERIES.INTEREST_RATES` | MPR, BCP/BCU sovereign bonds, PDBC rates |
-| `SERIES.MONEY` | M1, M2, M3, bank loans by type |
-| `SERIES.NATIONAL_ACCOUNTS` | Imacec and components |
-| `SERIES.EXTERNAL_SECTOR` | Current account, exports, imports, FDI |
-| `SERIES.EMPLOYMENT` | Unemployment rate, labour force, employed/unemployed |
-| `SERIES.PUBLIC_FINANCES` | Government revenue, expenditure, fiscal balance |
-| `SERIES.CAPITAL_MARKET` | IPSA, stock market capitalisation |
+| Group                      | Description                                          |
+| -------------------------- | ---------------------------------------------------- |
+| `SERIES.EXCHANGE_RATE`     | USD/CLP and major currency pairs                     |
+| `SERIES.PRICES`            | UF, UTM, IVP, CPI and components                     |
+| `SERIES.INTEREST_RATES`    | MPR, BCP/BCU sovereign bonds, PDBC rates             |
+| `SERIES.MONEY`             | M1, M2, M3, bank loans by type                       |
+| `SERIES.NATIONAL_ACCOUNTS` | Imacec and components                                |
+| `SERIES.EXTERNAL_SECTOR`   | Current account, exports, imports, FDI               |
+| `SERIES.EMPLOYMENT`        | Unemployment rate, labour force, employed/unemployed |
+| `SERIES.PUBLIC_FINANCES`   | Government revenue, expenditure, fiscal balance      |
+| `SERIES.CAPITAL_MARKET`    | IPSA, stock market capitalisation                    |
 
 Use [si3.bcentral.cl](https://si3.bcentral.cl/siete) or `client.searchSeries()` to discover additional series IDs beyond the curated set.
 
@@ -148,43 +209,44 @@ Use [si3.bcentral.cl](https://si3.bcentral.cl/siete) or `client.searchSeries()`
 
 #### Transform functions
 
-| Function | Description |
-| -------- | ----------- |
-| `parseValue(value)` | Parses a value string to `number \| null` (`null` for empty or non-numeric) |
-| `filterValid(observations)` | Returns only observations with parseable numeric values |
-| `toNumbers(observations)` | Maps observations to `Array<number \| null>` |
-| `toMap(observations)` | Returns a `Map<string, number \| null>` keyed by `indexDateString` |
-| `toArrays(observations)` | Returns `{ dates: Date[], values: Array<number \| null> }` |
-| `parseObservationDate(dateString)` | Parses `"DD-MM-YYYY"` to a UTC `Date` |
-| `formatQueryDate(date)` | Formats a `Date` to `"YYYY-MM-DD"` for use in `getSeries` options |
+| Function                           | Description                                                                                                          |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `parseValue(value)`                | Parses a value string to `number \| null` (`null` for empty or non-numeric)                                          |
+| `filterValid(observations)`        | Returns only observations with parseable numeric values                                                              |
+| `toNumbers(observations)`          | Maps observations to `Array<number \| null>`                                                                         |
+| `toMap(observations)`              | Returns a `Map<string, number \| null>` keyed by `indexDateString`                                                   |
+| `toArrays(observations)`           | Returns `{ dates: Date[], values: Array<number \| null> }`                                                           |
+| `fillForward(observations)`        | Fills gap observations by carrying the last valid value forward. Throws if the first observation has no valid value. |
+| `parseObservationDate(dateString)` | Parses `"DD-MM-YYYY"` to a UTC `Date`                                                                                |
+| `formatQueryDate(date)`            | Formats a `Date` to `"YYYY-MM-DD"` for use in `getSeries` options                                                    |
 
 #### Statistics functions
 
 All stats functions operate on `Observation[]` and ignore gap values (empty or non-numeric).
 
-| Function | Description |
-| -------- | ----------- |
-| `mean(observations)` | Arithmetic mean |
-| `stdDev(observations)` | Sample standard deviation (Bessel's correction) |
-| `min(observations)` | Minimum value |
-| `max(observations)` | Maximum value |
-| `periodVariation(observations)` | Period-over-period fractional change (`value[i] / value[i-1] - 1`) |
-| `annualVariation(observations, periodsPerYear)` | Year-over-year fractional change (`value[i] / value[i - n] - 1`) |
-| `rollingMean(observations, window)` | Rolling mean over a fixed window; `null` if any value in window is a gap |
+| Function                                        | Description                                                              |
+| ----------------------------------------------- | ------------------------------------------------------------------------ |
+| `mean(observations)`                            | Arithmetic mean                                                          |
+| `stdDev(observations)`                          | Sample standard deviation (Bessel's correction)                          |
+| `min(observations)`                             | Minimum value                                                            |
+| `max(observations)`                             | Maximum value                                                            |
+| `periodVariation(observations)`                 | Period-over-period fractional change (`value[i] / value[i-1] - 1`)       |
+| `annualVariation(observations, periodsPerYear)` | Year-over-year fractional change (`value[i] / value[i - n] - 1`)         |
+| `rollingMean(observations, window)`             | Rolling mean over a fixed window; `null` if any value in window is a gap |
 
-## Releases
+## Terms of Use
 
-```sh
-# 1. Regenerate CHANGELOG.md (auto-determines next version)
-npm run changelog
+Use of the Banco Central de Chile API is subject to their [terms and conditions](https://si3.bcentral.cl/estadisticas/Principal1/Web_Services/index_BDE_TC.htm). Key points:
 
-# 2. Commit and bump version
-git add CHANGELOG.md && git commit -m "chore: release vX.Y.Z"
-npm version patch  # or minor / major
+- **Registration required** — you must register and accept the terms at [si3.bcentral.cl](https://si3.bcentral.cl/siete) to obtain credentials.
+- **Rate limit** — maximum 5 simultaneous requests per second per account. The API does not support bulk or parallel fetching.
+- **Attribution** — any application or publication that uses data from this API must credit **Banco Central de Chile** as the original source.
 
-# 3. Push — the publish workflow triggers automatically on the version tag
-git push --follow-tags
-```
+This library does not redistribute any data. All data is fetched directly from the official API at runtime by the consuming application.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

package/dist/cache/index.d.ts

@@ -0,0 +1,4 @@
+export type { Cache } from './types.js';
+export { MemoryCache } from './memory-cache.js';
+export type { MemoryCacheOptions } from './memory-cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,2 @@
+export { MemoryCache } from './memory-cache.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/cache/memory-cache.d.ts

@@ -0,0 +1,42 @@
+import type { Cache } from './types.js';
+/**
+ * Options for {@link MemoryCache}.
+ */
+export interface MemoryCacheOptions {
+    /**
+     * Default time-to-live in milliseconds applied to every `set` call that
+     * does not provide its own `ttlMs`.
+     *
+     * When omitted, entries never expire unless a per-entry `ttlMs` is passed
+     * to `set`.
+     *
+     * @defaultValue `undefined` (no expiry)
+     */
+    defaultTtlMs?: number;
+}
+/**
+ * In-memory {@link Cache} implementation backed by a `Map`.
+ *
+ * Expired entries are evicted lazily on `get` — no background timers are
+ * created. Suitable for single-process use; does not persist across restarts.
+ *
+ * @example
+ * ```ts
+ * import { Client } from 'bcchapi/client';
+ * import { MemoryCache } from 'bcchapi/cache';
+ *
+ * const client = new Client({
+ *   user: 'me@example.com',
+ *   pass: 'secret',
+ *   cache: new MemoryCache({ defaultTtlMs: 60 * 60 * 1000 }), // 1 hour
+ * });
+ * ```
+ */
+export declare class MemoryCache implements Cache {
+    private readonly store;
+    private readonly defaultTtlMs;
+    constructor(options?: MemoryCacheOptions);
+    get(key: string): unknown;
+    set(key: string, value: unknown, ttlMs?: number): void;
+}
+//# sourceMappingURL=memory-cache.d.ts.map

package/dist/cache/memory-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache.d.ts","sourceRoot":"","sources":["../../src/cache/memory-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAOxC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,WAAY,YAAW,KAAK;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;gBAEtC,OAAO,CAAC,EAAE,kBAAkB;IAIxC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAYzB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;CAKvD"}

package/dist/cache/memory-cache.js

@@ -0,0 +1,42 @@
+/**
+ * In-memory {@link Cache} implementation backed by a `Map`.
+ *
+ * Expired entries are evicted lazily on `get` — no background timers are
+ * created. Suitable for single-process use; does not persist across restarts.
+ *
+ * @example
+ * ```ts
+ * import { Client } from 'bcchapi/client';
+ * import { MemoryCache } from 'bcchapi/cache';
+ *
+ * const client = new Client({
+ *   user: 'me@example.com',
+ *   pass: 'secret',
+ *   cache: new MemoryCache({ defaultTtlMs: 60 * 60 * 1000 }), // 1 hour
+ * });
+ * ```
+ */
+export class MemoryCache {
+    store = new Map();
+    defaultTtlMs;
+    constructor(options) {
+        this.defaultTtlMs = options?.defaultTtlMs;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        const effectiveTtl = ttlMs ?? this.defaultTtlMs;
+        const expiresAt = effectiveTtl !== undefined ? Date.now() + effectiveTtl : null;
+        this.store.set(key, { value, expiresAt });
+    }
+}
+//# sourceMappingURL=memory-cache.js.map

package/dist/cache/memory-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache.js","sourceRoot":"","sources":["../../src/cache/memory-cache.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,WAAW;IACL,KAAK,GAAG,IAAI,GAAG,EAAiB,CAAC;IACjC,YAAY,CAAqB;IAElD,YAAY,OAA4B;QACtC,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;IAC5C,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAC7D,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAc,EAAE,KAAc;QAC7C,MAAM,YAAY,GAAG,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QAChD,MAAM,SAAS,GAAG,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC;QAChF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5C,CAAC;CACF"}

package/dist/cache/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A minimal cache interface for storing and retrieving API responses.
+ *
+ * Implement this interface to plug in any caching backend (in-memory, Redis,
+ * SQLite, etc.) into {@link https://github.com/airarrazaval/bcchapi | Client}.
+ *
+ * @example
+ * ```ts
+ * import type { Cache } from 'bcchapi/cache';
+ * import { createClient } from 'redis';
+ *
+ * const redis = await createClient().connect();
+ *
+ * const redisCache: Cache = {
+ *   get: async (key) => {
+ *     const raw = await redis.get(key);
+ *     return raw === null ? undefined : JSON.parse(raw);
+ *   },
+ *   set: async (key, value, ttlMs) => {
+ *     const opts = ttlMs !== undefined ? { PX: ttlMs } : {};
+ *     await redis.set(key, JSON.stringify(value), opts);
+ *   },
+ * };
+ * ```
+ */
+export interface Cache {
+    /**
+     * Returns the cached value for `key`, or `undefined` on a miss.
+     *
+     * @param key - Cache key.
+     * @returns The stored value, or `undefined` if the key is absent or expired.
+     */
+    get(key: string): unknown;
+    /**
+     * Stores `value` under `key` with an optional time-to-live.
+     *
+     * @param key - Cache key.
+     * @param value - Value to store.
+     * @param ttlMs - Optional time-to-live in milliseconds. Implementations may
+     *   ignore this if TTL is managed externally (e.g. Redis `EXPIRE`).
+     */
+    set(key: string, value: unknown, ttlMs?: number): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cache/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,KAAK;IACpB;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE1B;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxD"}

package/dist/cache/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cache/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/cache/types.ts"],"names":[],"mappings":""}

package/dist/client/client.d.ts

@@ -17,6 +17,8 @@ export declare class Client {
     private readonly user;
     private readonly pass;
     private readonly fetch;
+    private readonly cache;
+    private readonly cacheTtlMs;
     constructor(options: ClientOptions);
     /**
      * Fetches observations for a single time series.

package/dist/client/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,gBAAgB,EAEhB,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAyCpB;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;gBAEpC,OAAO,EAAE,aAAa;IAMlC;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA+BlF;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAuB/D,OAAO,CAAC,UAAU;YAOJ,OAAO;CAgBtB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,aAAa,EACb,SAAS,EACT,gBAAgB,EAEhB,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAyCpB;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAEpC,OAAO,EAAE,aAAa;IAQlC;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA2ClF;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAmC/D,OAAO,CAAC,UAAU;YAOJ,OAAO;CAgBtB"}

package/dist/client/client.js

@@ -18,10 +18,14 @@ export class Client {
     user;
     pass;
     fetch;
+    cache;
+    cacheTtlMs;
     constructor(options) {
         this.user = options.user;
         this.pass = options.pass;
         this.fetch = options.fetch ?? globalThis.fetch;
+        this.cache = options.cache;
+        this.cacheTtlMs = options.cacheTtlMs;
     }
     /**
      * Fetches observations for a single time series.
@@ -43,6 +47,13 @@ export class Client {
      * ```
      */
     async getSeries(seriesId, options) {
+        const cacheKey = `getSeries:${seriesId}:${options?.firstdate ?? ''}:${options?.lastdate ?? ''}`;
+        if (this.cache !== undefined) {
+            const cached = this.cache.get(cacheKey);
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
         const params = this.baseParams();
         params.set('function', 'GetSeries');
         params.set('timeseries', seriesId);
@@ -61,12 +72,14 @@ export class Client {
             value: obs.value,
             statusCode: obs.statusCode,
         }));
-        return {
+        const result = {
             seriesId: raw.Series.seriesId,
             descripEsp: raw.Series.descripEsp,
             descripIng: raw.Series.descripIng,
             observations,
         };
+        this.cache?.set(cacheKey, result, this.cacheTtlMs);
+        return result;
     }
     /**
      * Searches for available series filtered by observation frequency.
@@ -84,6 +97,13 @@ export class Client {
      * ```
      */
     async searchSeries(frequency) {
+        const cacheKey = `searchSeries:${frequency}`;
+        if (this.cache !== undefined) {
+            const cached = this.cache.get(cacheKey);
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
         const params = this.baseParams();
         params.set('function', 'SearchSeries');
         params.set('frequency', frequency);
@@ -91,7 +111,7 @@ export class Client {
         if (raw.Codigo !== 0) {
             throw new ApiError(`BCCH API error: ${raw.Descripcion}`, raw.Codigo, raw.Descripcion);
         }
-        return (raw.SeriesInfos ?? []).map((info) => ({
+        const result = (raw.SeriesInfos ?? []).map((info) => ({
             seriesId: info.seriesId,
             frequencyCode: info.frequencyCode,
             spanishTitle: info.spanishTitle,
@@ -101,6 +121,8 @@ export class Client {
             updatedAt: info.updatedAt,
             createdAt: info.createdAt,
         }));
+        this.cache?.set(cacheKey, result, this.cacheTtlMs);
+        return result;
     }
     baseParams() {
         const params = new URLSearchParams();

package/dist/client/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
 export { Client } from './client.js';
 export { ApiError, HttpError } from './types.js';
-export type { ClientOptions, Frequency, GetSeriesOptions, Observation, SeriesData, SeriesInfo, } from './types.js';
+export type { Cache, ClientOptions, Frequency, GetSeriesOptions, Observation, SeriesData, SeriesInfo, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACjD,YAAY,EACV,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACjD,YAAY,EACV,KAAK,EACL,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/client/types.d.ts

@@ -1,3 +1,4 @@
+import type { Cache } from '../cache/types.js';
 /**
  * Credentials and configuration for {@link Client}.
  */
@@ -15,7 +16,32 @@ export interface ClientOptions {
      * @defaultValue `globalThis.fetch`
      */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Optional cache backend for storing API responses.
+     *
+     * Any object implementing the {@link Cache} interface is accepted — use
+     * `MemoryCache` from `bcchapi/cache` for a zero-config in-memory option,
+     * or provide your own adapter (Redis, SQLite, etc.).
+     *
+     * When omitted, every call makes a fresh HTTP request.
+     *
+     * @example
+     * ```ts
+     * import { MemoryCache } from 'bcchapi/cache';
+     * const client = new Client({ user, pass, cache: new MemoryCache() });
+     * ```
+     */
+    cache?: Cache;
+    /**
+     * Time-to-live in milliseconds passed to `cache.set` on every successful
+     * response. Applies to both `getSeries` and `searchSeries`.
+     *
+     * When omitted, `cache.set` is called without a TTL argument and expiry is
+     * determined by the cache implementation.
+     */
+    cacheTtlMs?: number;
 }
+export type { Cache } from '../cache/types.js';
 /**
  * A single observation returned by the BCCH API.
  *

package/dist/client/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IAEnB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IAEnB,qDAAqD;IACrD,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IAEtB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IAErB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IAErB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC;IAEzB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;IAExB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAElB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAMrE;;;;;;;;;;;;;GAaG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAMjE;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAEhC;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IAEnB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IAEnB,qDAAqD;IACrD,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IAEtB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IAErB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IAErB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC;IAEzB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;IAExB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAElB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAMrE;;;;;;;;;;;;;GAaG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAMjE;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C"}

package/dist/client/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAoHA,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,qDAAqD;IAC5C,MAAM,CAAS;IAExB,kDAAkD;IACzC,WAAW,CAAS;IAE7B,YAAY,OAAe,EAAE,MAAc,EAAE,WAAmB;QAC9D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,wBAAwB;IACf,MAAM,CAAS;IAExB,YAAY,OAAe,EAAE,MAAc;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAkJA,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,qDAAqD;IAC5C,MAAM,CAAS;IAExB,kDAAkD;IACzC,WAAW,CAAS;IAE7B,YAAY,OAAe,EAAE,MAAc,EAAE,WAAmB;QAC9D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,wBAAwB;IACf,MAAM,CAAS;IAExB,YAAY,OAAe,EAAE,MAAc;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { Client, ApiError, HttpError } from './client/index.js';
-export type { ClientOptions, Frequency, GetSeriesOptions, Observation, SeriesData, SeriesInfo, } from './client/index.js';
+export type { Cache, ClientOptions, Frequency, GetSeriesOptions, Observation, SeriesData, SeriesInfo, } from './client/index.js';
+export { MemoryCache } from './cache/index.js';
+export type { MemoryCacheOptions } from './cache/index.js';
 export { SERIES } from './series/index.js';
-export { parseObservationDate, formatQueryDate, filterValid, parseValue, toArrays, toMap, toNumbers, annualVariation, max, mean, min, periodVariation, rollingMean, stdDev, } from './utils/index.js';
+export { parseObservationDate, formatQueryDate, fillForward, filterValid, parseValue, toArrays, toMap, toNumbers, annualVariation, max, mean, min, periodVariation, rollingMean, stdDev, } from './utils/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EACV,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,UAAU,EACV,QAAQ,EACR,KAAK,EACL,SAAS,EACT,eAAe,EACf,GAAG,EACH,IAAI,EACJ,GAAG,EACH,eAAe,EACf,WAAW,EACX,MAAM,GACP,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EACV,KAAK,EACL,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,KAAK,EACL,SAAS,EACT,eAAe,EACf,GAAG,EACH,IAAI,EACJ,GAAG,EACH,eAAe,EACf,WAAW,EACX,MAAM,GACP,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export { Client, ApiError, HttpError } from './client/index.js';
+export { MemoryCache } from './cache/index.js';
 export { SERIES } from './series/index.js';
-export { parseObservationDate, formatQueryDate, filterValid, parseValue, toArrays, toMap, toNumbers, annualVariation, max, mean, min, periodVariation, rollingMean, stdDev, } from './utils/index.js';
+export { parseObservationDate, formatQueryDate, fillForward, filterValid, parseValue, toArrays, toMap, toNumbers, annualVariation, max, mean, min, periodVariation, rollingMean, stdDev, } from './utils/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAUhE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,UAAU,EACV,QAAQ,EACR,KAAK,EACL,SAAS,EACT,eAAe,EACf,GAAG,EACH,IAAI,EACJ,GAAG,EACH,eAAe,EACf,WAAW,EACX,MAAM,GACP,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAWhE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,KAAK,EACL,SAAS,EACT,eAAe,EACf,GAAG,EACH,IAAI,EACJ,GAAG,EACH,eAAe,EACf,WAAW,EACX,MAAM,GACP,MAAM,kBAAkB,CAAC"}

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
 export { formatQueryDate, parseObservationDate } from './dates.js';
-export { filterValid, parseValue, toArrays, toMap, toNumbers } from './transform.js';
+export { fillForward, filterValid, parseValue, toArrays, toMap, toNumbers } from './transform.js';
 export { annualVariation, max, mean, min, periodVariation, rollingMean, stdDev } from './stats.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC"}

package/dist/utils/index.js

@@ -1,4 +1,4 @@
 export { formatQueryDate, parseObservationDate } from './dates.js';
-export { filterValid, parseValue, toArrays, toMap, toNumbers } from './transform.js';
+export { fillForward, filterValid, parseValue, toArrays, toMap, toNumbers } from './transform.js';
 export { annualVariation, max, mean, min, periodVariation, rollingMean, stdDev } from './stats.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC"}

package/dist/utils/transform.d.ts

@@ -1,4 +1,23 @@
 import type { Observation } from '../client/types.js';
+/**
+ * Fills forward gap observations using the last valid value seen.
+ *
+ * Each gap (empty or non-numeric `value`) is replaced with the `value` string
+ * of the most recent valid observation. The original `indexDateString` and
+ * `statusCode` of each observation are preserved.
+ *
+ * @param observations - Array of observations to fill.
+ * @returns A new array of the same length with gaps filled forward.
+ * @throws {Error} When the first observation has no valid value. Ensure the
+ *   start date falls on a trading day with an available observation.
+ *
+ * @example
+ * ```ts
+ * const filled = fillForward(data.observations);
+ * // Gap observations now carry the last known value forward
+ * ```
+ */
+export declare function fillForward(observations: Observation[]): Observation[];
 /**
  * Parses a raw observation value string to a number, or `null` for gaps.
  *

package/dist/utils/transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/utils/transform.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAEtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAE3E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAM7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG;IACrD,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC9B,CAQA"}
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/utils/transform.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAmBtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAEtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAE3E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAM7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG;IACrD,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC9B,CAQA"}

package/dist/utils/transform.js

@@ -1,4 +1,38 @@
 import { parseObservationDate } from './dates.js';
+/**
+ * Fills forward gap observations using the last valid value seen.
+ *
+ * Each gap (empty or non-numeric `value`) is replaced with the `value` string
+ * of the most recent valid observation. The original `indexDateString` and
+ * `statusCode` of each observation are preserved.
+ *
+ * @param observations - Array of observations to fill.
+ * @returns A new array of the same length with gaps filled forward.
+ * @throws {Error} When the first observation has no valid value. Ensure the
+ *   start date falls on a trading day with an available observation.
+ *
+ * @example
+ * ```ts
+ * const filled = fillForward(data.observations);
+ * // Gap observations now carry the last known value forward
+ * ```
+ */
+export function fillForward(observations) {
+    if (observations.length === 0) {
+        return [];
+    }
+    if (parseValue(observations[0].value) === null) {
+        throw new Error('fillForward: first observation has no valid value — ensure the start date falls on a trading day');
+    }
+    let lastValue = observations[0].value;
+    return observations.map((obs) => {
+        if (parseValue(obs.value) !== null) {
+            lastValue = obs.value;
+            return obs;
+        }
+        return { ...obs, value: lastValue };
+    });
+}
 /**
  * Parses a raw observation value string to a number, or `null` for gaps.
  *

package/dist/utils/transform.js.map

@@ -1 +1 @@
-{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../src/utils/transform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGlD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,YAA2B;IACrD,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,YAA2B;IACnD,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,KAAK,CAAC,YAA2B;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAC;IAChD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CAAC,YAA2B;IAIlD,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,MAAM,MAAM,GAAyB,EAAE,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../src/utils/transform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGlD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAAC,YAA2B;IACrD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,kGAAkG,CACnG,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,GAAG,YAAY,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC;IACvC,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAC9B,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;YACnC,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC;YACtB,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,YAA2B;IACrD,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,YAA2B;IACnD,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,KAAK,CAAC,YAA2B;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAC;IAChD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CAAC,YAA2B;IAIlD,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,MAAM,MAAM,GAAyB,EAAE,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bcchapi",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "Node.js wrapper for the Banco Central de Chile API. Features a fully typed API client and utility tools to streamline macroeconomic data integration.",
   "homepage": "https://github.com/airarrazaval/bcchapi#readme",
   "bugs": {
@@ -19,9 +19,6 @@
   ],
   "type": "module",
   "sideEffects": false,
-  "publishConfig": {
-    "access": "public"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -42,8 +39,16 @@
       "types": "./dist/utils/index.d.ts",
       "import": "./dist/utils/index.js",
       "default": "./dist/utils/index.js"
+    },
+    "./cache": {
+      "types": "./dist/cache/index.d.ts",
+      "import": "./dist/cache/index.js",
+      "default": "./dist/cache/index.js"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "node --import tsx/esm --test --watch \"tests/**/*.test.ts\"",
@@ -54,15 +59,16 @@
     "lint:fix": "oxlint --fix src tests",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
+    "check": "npm run typecheck && npm run lint && npm test",
     "clean": "rm -rf dist docs",
     "docs": "typedoc",
     "changelog": "git-cliff --bump -o CHANGELOG.md",
-    "prepublishOnly": "npm run typecheck && npm run lint && npm run clean && npm run build"
+    "prepublishOnly": "npm run check && npm run clean && npm run build"
   },
   "devDependencies": {
     "@types/node": "^24.12.0",
     "git-cliff": "^2.12.0",
-    "oxfmt": "^0.36.0",
+    "oxfmt": "^0.37.0",
     "oxlint": "^1.51.0",
     "tsx": "^4.21.0",
     "typedoc": "^0.28.17",