@dereekb/util 13.26.0 → 13.27.0

package/oidc/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/oidc",
-  "version": "13.26.0",
+  "version": "13.27.0",
   "peerDependencies": {
-    "@dereekb/util": "13.26.0"
+    "@dereekb/util": "13.27.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "13.26.0",
+  "version": "13.27.0",
   "sideEffects": false,
   "exports": {
     "./test": {

package/src/lib/getter/getter.cache.expiring.d.ts

@@ -0,0 +1,101 @@
+import { type Maybe } from '../value/maybe.type';
+import { type DateOrUnixDateTimeMillisecondsNumber, type Milliseconds } from '../date/date';
+import { type ExpirationDetails } from '../date/expires';
+import { type FactoryWithInput, type Getter } from './getter';
+import { type CachedFactoryWithInput } from './getter.cache';
+/**
+ * Function that derives the expiration for a cached value.
+ *
+ * Returns the absolute Date/epoch-milliseconds at which `value` should expire, or null/undefined for a
+ * value that never expires. `loadedAt` is the time the value was loaded into the cache, so a value-derived
+ * TTL is expressed as `addMilliseconds(loadedAt, ttl)`.
+ */
+export type ExpiringCachedGetterExpirationFunction<T> = (value: T, loadedAt: Date) => Maybe<DateOrUnixDateTimeMillisecondsNumber>;
+/**
+ * Configuration for {@link expiringCachedGetter}().
+ */
+export interface ExpiringCachedGetterConfig<T, A = unknown> {
+    /**
+     * The getter/factory whose result is cached. It is wrapped by an internal {@link cachedGetter}, which owns
+     * the load/init/reset/used mechanics — this getter only layers expiration on top.
+     */
+    readonly getter: FactoryWithInput<T, A>;
+    /**
+     * Fixed time-to-live in milliseconds, measured from the moment the value is loaded. Ignored when
+     * `expiration` is provided.
+     */
+    readonly ttl?: Maybe<Milliseconds>;
+    /**
+     * Derives the expiration from the loaded value itself (a "value-derived" expiring cache). Takes precedence
+     * over `ttl`. Return null/undefined for a value that never expires.
+     *
+     * When the value is (or contains) an `Expires`, pass `(value) => value.expiresAt`; for a value-derived TTL
+     * use `(value, loadedAt) => addMilliseconds(loadedAt, ttlOf(value))`.
+     */
+    readonly expiration?: Maybe<ExpiringCachedGetterExpirationFunction<T>>;
+    /**
+     * How the expiration details are resolved:
+     * - `false` (default): the details are computed ONCE, when the value is loaded, and reused for every check.
+     * - `true` (dynamic): the details are recomputed from the cached value on every retrieval and on every
+     *   {@link ExpiringCachedGetter.expirationDetails} call. Use this when the derived expiration can change
+     *   after the value is loaded.
+     */
+    readonly dynamic?: Maybe<boolean>;
+    /**
+     * A freshly-loaded value is returned WITHOUT an expiration check by default — it was just produced by the
+     * source, so it is assumed valid. Set this true to check a freshly-loaded value too: if the source returns
+     * a value that is ALREADY expired, an error is thrown rather than caching a dead-on-arrival value. Applies
+     * to the initial load and to every reload after expiry.
+     */
+    readonly checkExpirationOnFirstGet?: Maybe<boolean>;
+    /**
+     * Getter for the current time. Defaults to `() => new Date()`. Override to make expiry deterministic in tests.
+     */
+    readonly now?: Maybe<Getter<Date>>;
+}
+/**
+ * A cached getter whose cached value expires; once the value has expired the next retrieval reloads it from
+ * the source.
+ *
+ * Extends the {@link CachedGetter} surface (`set`/`reset`/`init`/`used`, all delegated to an internal
+ * {@link cachedGetter}) with a single expiration probe.
+ */
+export type ExpiringCachedGetter<T, A = unknown> = CachedFactoryWithInput<T, A> & {
+    /**
+     * Returns the {@link ExpirationDetails} of the currently cached value, or null when no value is cached.
+     *
+     * In `dynamic` mode the details are recomputed from the current value on each call; otherwise the details
+     * computed at load time are returned. Use the returned object's `hasExpired()` / `getExpirationDate()`.
+     */
+    expirationDetails(): Maybe<ExpirationDetails>;
+};
+/**
+ * Creates an {@link ExpiringCachedGetter} from the input configuration.
+ *
+ * The value is loaded and cached by an internal {@link cachedGetter}; this getter layers expiration on top —
+ * once the cached value expires the next retrieval resets the internal cache and reloads. Expiration is
+ * configured one of two ways:
+ *
+ * - **Fixed TTL** — pass `ttl` (milliseconds); the value expires that long after it is loaded.
+ * - **Value-derived** — pass an `expiration` function deriving the expiration Date/epoch-ms from the loaded
+ *   value (e.g. `(value) => value.expiresAt`, or `(value, loadedAt) => addMilliseconds(loadedAt, ttlOf(value))`).
+ *   Returning null/undefined means "never expires". `expiration` takes precedence over `ttl`; with neither set
+ *   the value never expires (matching {@link cachedGetter}).
+ *
+ * A freshly-loaded value is returned without an expiration check; set `checkExpirationOnFirstGet` to reject a
+ * dead-on-arrival value with an error instead. Set `dynamic` to recompute the expiration details on every
+ * retrieval rather than once at load. Use {@link ExpiringCachedGetter.expirationDetails} to inspect the current
+ * expiration state.
+ *
+ * @param config - The getter to cache plus its expiration configuration.
+ * @returns An ExpiringCachedGetter that caches the value until it expires.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory getter
+ * @dbxUtilKind factory
+ * @dbxUtilTags getter, cache, expire, expiring, ttl, time-to-live, refresh, memoize, lazy, factory
+ * @dbxUtilRelated cached-getter, expiration-details, is-expired, calculate-expiration-date
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function expiringCachedGetter<T, A = unknown>(config: ExpiringCachedGetterConfig<T, A>): ExpiringCachedGetter<T, A>;

package/src/lib/getter/index.d.ts

@@ -2,4 +2,5 @@ export * from './type';
 export * from './getter';
 export * from './getter.util';
 export * from './getter.cache';
+export * from './getter.cache.expiring';
 export * from './getter.map';

package/test/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/test",
-  "version": "13.26.0",
+  "version": "13.27.0",
   "peerDependencies": {
-    "@dereekb/util": "13.26.0",
+    "@dereekb/util": "13.27.0",
     "make-error": "^1.3.6"
   },
   "exports": {