@chilkat/react-native 11.6.1

package/src/specs/Cache.nitro.ts

@@ -0,0 +1,483 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { BinData } from './BinData.nitro'
+import type { CkDateTime } from './CkDateTime.nitro'
+import type { StringBuilder } from './StringBuilder.nitro'
+
+/**
+ * Store, retrieve, expire, and clean up cached text or binary data on disk.
+ *
+ * `Cache` is a disk-based cache class for storing and
+ * retrieving text or binary items by unique key. It provides configurable cache
+ * roots, optional multi-level directory layout, expiration metadata, ETag
+ * metadata, cache lookup, fetch-status properties, expiration updates, and
+ * cleanup methods for deleting individual items, expired items, older items, or
+ * the entire cache.
+ *
+ * **Key-based storage**
+ *
+ * Store and retrieve cached items by unique key, without the application
+ * needing to manage the underlying cache filenames directly.
+ *
+ * **Text and binary data**
+ *
+ * Cache strings, byte data, files, or Chilkat buffer objects depending on
+ * the data form used by the application.
+ *
+ * **Expiration control**
+ *
+ * Associate cached items with expiration times, update expiration metadata,
+ * and check whether cached content is still usable.
+ *
+ * **ETag metadata**
+ *
+ * Store and retrieve ETag values for workflows that need HTTP-style cache
+ * validation or conditional re-fetch logic.
+ *
+ * **Configurable layout**
+ *
+ * Choose the cache root directory and use an optional multi-level directory
+ * structure to avoid too many files in a single folder.
+ *
+ * **Cleanup operations**
+ *
+ * Delete a single cached item, remove expired items, remove older items, or
+ * clear the entire cache when needed.
+ *
+ * **Common pattern:**
+ * Configure the cache root, choose the key used to identify each item, check
+ * whether a valid cached copy exists, fetch or regenerate the content when
+ * needed, store it with expiration and optional ETag metadata, and periodically
+ * clean up expired or old cached items.
+ *
+ * For an extended overview, see
+ * [Cache Class Overview](https://www.chilkatsoft.com/cache_class_overview.asp).
+ *
+ * Each `Cache` instance owns a native Chilkat object. It is released when the JavaScript object is
+ * garbage collected, or immediately by `dispose()`; any use after `dispose()` throws.
+ * Create one with `new Cache()`.
+ */
+export interface Cache extends HybridObject<{ ios: 'c++', android: 'c++' }> {
+  // ---- Properties ----
+
+  /**
+   * Provides HTML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorHtml: string
+
+  /**
+   * Provides plain text information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorText: string
+
+  /**
+   * Provides XML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorXml: string
+
+  /**
+   * Version of the component/library, such as "10.1.0"
+   *
+   * This property is read-only.
+   */
+  readonly version: string
+
+  /**
+   * If set to a file path, this property logs the LastErrorText of each Chilkat method or property
+   * call to the specified file. This logging helps identify the context and history of Chilkat
+   * calls leading up to any crash or hang, aiding in debugging.
+   *
+   * Enabling the VerboseLogging property provides more detailed information.
+   *
+   * This property is mainly used for debugging rare instances where a Chilkat method call causes a
+   * hang or crash, which should generally not happen.
+   *
+   * Possible causes of hangs include:
+   *
+   * - A timeout property set to 0, indicating an infinite timeout.
+   *
+   * - A hang occurring within an event callback in the application code.
+   *
+   * - An internal bug in the Chilkat code causing the hang.
+   */
+  debugLogFilePath: string
+
+  /**
+   * If set to `true`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may
+   * contain more verbose information. The default value is `false`. Verbose logging should only be
+   * used for debugging. The potentially large quantity of logged information may adversely affect
+   * peformance.
+   */
+  verboseLogging: boolean
+
+  /**
+   * Indicates the success or failure of the most recent method call: `true` means success, `false`
+   * means failure. This property remains unchanged by property setters or getters. This method is
+   * present to address challenges in checking for null or Nothing returns in certain programming
+   * languages. Note: This property does not apply to methods that return integer values or to
+   * boolean-returning methods where the boolean does not indicate success or failure.
+   */
+  lastMethodSuccess: boolean
+
+  /**
+   * Returns the ETag metadata associated with the most recently fetched cache item. An empty string
+   * means that the fetched item has no stored ETag.
+   *
+   * **Read after a fetch:** This property describes the item returned by the most recent successful
+   * fetch operation, such as {@link Cache.fetchBd}, {@link Cache.fetchSb}, or {@link
+   * Cache.fetchText}.
+   *
+   * **ETags are opaque metadata:** The cache stores and returns the string but does not interpret
+   * it. Applications commonly use an HTTP ETag with conditional requests such as `If-None-Match`.
+   *
+   * This property is read-only.
+   */
+  readonly lastEtagFetched: string
+
+  /**
+   * Returns the expiration date and time stored for the most recently fetched cache item, formatted
+   * as an RFC 822-style Internet date. An empty string represents an item with no expiration date.
+   *
+   * **Expiration is metadata:** Fetching an expired item is still possible. Read {@link
+   * Cache.lastHitExpired} after the fetch to determine whether the returned entry is stale.
+   *
+   * This property is read-only.
+   */
+  readonly lastExpirationFetchedStr: string
+
+  /**
+   * Returns `true` when the expiration time of the most recently fetched item is earlier than the
+   * current system date and time; otherwise returns `false`.
+   *
+   * **Expired does not mean deleted:** Expiration marks an entry as stale. The file remains in the
+   * cache until it is replaced or removed by methods such as {@link Cache.deleteAllExpired} or
+   * {@link Cache.deleteFromCache}.
+   *
+   * This property is read-only.
+   */
+  readonly lastHitExpired: boolean
+
+  /**
+   * Returns the application-defined key associated with the most recently fetched cache item.
+   *
+   * **Keys are not limited to URLs:** A canonicalized URL is a common key for cached web content,
+   * but any unique string may be used. Reusing a key causes a save operation to replace the
+   * existing item for that key.
+   *
+   * This property is read-only.
+   */
+  readonly lastKeyFetched: string
+
+  /**
+   * Gets or sets the number of directory levels used beneath each cache root. Valid values are `0`,
+   * `1`, and `2`.
+   *
+   * ValueDirectory layout
+   *
+   * | `0` |  | All cache files are stored directly in the cache root. |
+   *
+   * | `1` |  | Files are distributed among 256 first-level directories named `0` through `255`. |
+   *
+   * | `2` | | Files are distributed through two levels of 256 directories, allowing as many as
+   * 65,536 leaf directories per root. |
+   *
+   * **Configure before use:** Use the same level when reopening an existing cache. Changing the
+   * layout does not reorganize previously stored files and can prevent the object from locating
+   * them through their keys.
+   */
+  level: number
+
+  /**
+   * Returns the number of cache-root directories that have been registered by calling {@link
+   * Cache.addRoot}.
+   *
+   * **Multiple roots:** A cache may span more than one directory or storage device. Configure the
+   * same root set when reopening a persistent cache so previously stored items remain discoverable.
+   *
+   * This property is read-only.
+   */
+  readonly numRoots: number
+
+  // ---- Methods ----
+
+  /**
+   * Adds `path` as a root directory for the disk cache. Call this method once for each root that
+   * should participate in the cache.
+   *
+   * For example, a cache distributed across `D:\cacheRoot`, `E:\cacheRoot`, and `F:\cacheRoot` is
+   * configured by calling this method three times.
+   *
+   * **Use dedicated writable directories:** Cache cleanup methods can delete cache files beneath
+   * every configured root. Do not mix unrelated application files into a cache root.
+   *
+   * **Persistent configuration:** Recreate the same roots and {@link Cache.level} setting before
+   * accessing a cache created by an earlier process or application run.
+   */
+  addRoot(path: string): void
+
+  /**
+   * Deletes every cache item from all configured roots and returns the number of cache files
+   * removed. Multi-level subdirectories are retained.
+   *
+   * **Destructive operation:** This cannot be limited to a key prefix or reversed. Use cache roots
+   * dedicated to Chilkat cache data.
+   */
+  deleteAll(): number
+
+  /**
+   * Deletes all cache items whose stored expiration time is earlier than the current system time
+   * and returns the number of files removed.
+   *
+   * **Non-expiring entries remain:** Items saved without an expiration date are not removed by this
+   * method.
+   */
+  deleteAllExpired(): number
+
+  /**
+   * Deletes the cache item identified by `key`.
+   *
+   * Return valueMeaning
+   *
+   * | `true` |  | The item was deleted, or no item existed for the key. |
+   *
+   * | `false` | | The item exists but could not be deleted, for example because of a filesystem
+   * permission or sharing error. |
+   *
+   * **Idempotent deletion:** A missing key is not treated as an error, which makes it safe to call
+   * this method when the application merely wants to ensure that an item is absent.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  deleteFromCache(key: string): void
+
+  /**
+   * Deletes cache items older than the cutoff date and time supplied in `dt`.
+   *
+   * Returns the number of cache files deleted, or `-1` if an error occurs.
+   *
+   * **Different from expiration cleanup:** Use {@link Cache.deleteAllExpired} when the decision
+   * should be based specifically on each item's expiration metadata.
+   */
+  deleteOlderDt(dt: CkDateTime): number
+
+  /**
+   * Deletes cache items older than the cutoff date and time supplied in `dateTimeStr` as an RFC
+   * 822-style Internet date string.
+   *
+   * Returns the number of cache files deleted, or `-1` if an error occurs.
+   *
+   * **Date format:** A typical value is `Mon, 03 Aug 2026 12:00:00 GMT`. Use {@link
+   * Cache.deleteOlderDt} when the cutoff is already available as a `CkDateTime`.
+   */
+  deleteOlderStr(dateTimeStr: string): number
+
+  /**
+   * Retrieves the text item identified by `key` and returns its string content.
+   *
+   * The key is application-defined, may contain any characters, and must uniquely identify the
+   * intended item.
+   *
+   * **Freshness is separate:** A successful fetch can return an expired entry. Read {@link
+   * Cache.lastHitExpired} immediately afterward when the application requires only fresh data.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  fetchText(key: string): string
+
+  /**
+   * Returns the ETag metadata stored with the cache item identified by `key`.
+   *
+   * **Opaque value:** Chilkat does not parse or validate the ETag. An application may store any
+   * auxiliary string here, although HTTP entity tags are the common use case.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  getEtag(key: string): string
+
+  /**
+   * Returns the expiration date and time stored for the item identified by `url`, formatted as an
+   * RFC 822-style Internet date string.
+   *
+   * **Argument name:** Some language bindings name `url` `url` for historical reasons. It is the
+   * cache key and does not need to be a URL.
+   *
+   * **No-expiration entries:** An empty stored expiration represents an item that does not expire
+   * automatically.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  getExpirationStr(url: string): string
+
+  /**
+   * Returns the absolute filesystem path of the cache file associated with `key`.
+   *
+   * **Implementation detail:** Treat the returned path as diagnostic information. Applications
+   * should normally read, update, and delete entries through the `Cache` API rather than modifying
+   * cache files directly.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  getFilename(key: string): string
+
+  /**
+   * Returns the directory path of the cache root at zero-based `index`. Valid indexes range from
+   * `0` through `
0 - 1`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  getRoot(index: number): string
+
+  /**
+   * Returns `true` if an item exists for `key`, or `false` if the key is not present.
+   *
+   * **Presence is not freshness:** This method does not imply that the entry is unexpired. Fetch
+   * the item and examine {@link Cache.lastHitExpired}, or read its expiration metadata, when
+   * freshness matters.
+   */
+  isCached(key: string): boolean
+
+  /**
+   * Stores `itemTextData` as a text cache item under `key`, with the expiration date and time
+   * supplied in `expireDateTime`. If the key already exists, its data and metadata are replaced.
+   *
+   * `eTag` is optional ETag or application metadata and may be an empty string. The key may contain
+   * any characters and may be any length, but it must uniquely identify the item.
+   *
+   * **Expiration does not delete:** After the expiration time passes, the entry remains on disk and
+   * can still be fetched. Use {@link Cache.lastHitExpired} to detect staleness and a deletion
+   * method to remove it.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  saveTextDt(key: string, expireDateTime: CkDateTime, eTag: string, itemTextData: string): void
+
+  /**
+   * Stores `itemTextData` as a non-expiring text cache item under `key`. If the key already exists,
+   * its data and metadata are replaced.
+   *
+   * `eTag` is optional ETag or application metadata and may be an empty string.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  saveTextNoExpire(key: string, eTag: string, itemTextData: string): void
+
+  /**
+   * Stores `itemTextData` as a text cache item under `key`, with `expireDateTime` providing the
+   * expiration time as an RFC 822-style Internet date string. If the key already exists, its data
+   * and metadata are replaced.
+   *
+   * `eTag` is optional ETag or application metadata and may be empty.
+   *
+   * **Date alternatives:** Use {@link Cache.saveTextDt} when the expiration is available as a
+   * `CkDateTime`, or {@link Cache.saveTextNoExpire} for an entry without expiration.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  saveTextStr(key: string, expireDateTime: string, eTag: string, itemTextData: string): void
+
+  /**
+   * Replaces the expiration date and time of the cache item identified by `key` with the
+   * `CkDateTime` value supplied in `expireDateTime`. The cached data and ETag are unchanged.
+   *
+   * **Existing item required:** This method updates metadata; it does not create a new cache entry
+   * when the key is absent.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  updateExpirationDt(key: string, expireDateTime: CkDateTime): void
+
+  /**
+   * Replaces the expiration date and time of the cache item identified by `key` with the RFC
+   * 822-style Internet date string supplied in `expireDateTime`. The cached data and ETag are
+   * unchanged.
+   *
+   * **Argument name:** Some language bindings name `key` `url`; it is the cache key and does not
+   * need to be a URL. Use {@link Cache.updateExpirationDt} for a `CkDateTime` value.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  updateExpirationStr(key: string, expireDateTime: string): void
+
+  /**
+   * Retrieves the binary item identified by `key` and loads its bytes into the `BinData` object
+   * supplied in `bd`.
+   *
+   * The key is application-defined, may contain any characters, and must uniquely identify the
+   * intended item.
+   *
+   * **Check the return value:** Use the destination only when this method returns `true`. A failed
+   * lookup or filesystem error returns `false`.
+   *
+   * **Freshness:** A successful fetch may return an expired item. Read {@link Cache.lastHitExpired}
+   * immediately afterward when stale data must not be used.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  fetchBd(key: string, bd: BinData): void
+
+  /**
+   * Retrieves the text item identified by `key` and loads its content into the `StringBuilder`
+   * supplied in `sb`.
+   *
+   * The key is application-defined, may contain any characters, and must uniquely identify the
+   * intended item.
+   *
+   * **Check the return value:** Use the destination only when this method returns `true`. A failed
+   * lookup or filesystem error returns `false`.
+   *
+   * **Freshness:** A successful fetch may return an expired item. Read {@link Cache.lastHitExpired}
+   * immediately afterward when stale data must not be used.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  fetchSb(key: string, sb: StringBuilder): void
+
+  /**
+   * Stores the contents of `bd` as binary cache data under `key`. If the key already exists, its
+   * data and metadata are replaced.
+   *
+   * ArgumentPurpose
+   *
+   * | `key` |  | The unique application-defined cache key. |
+   *
+   * | `expiration` | | Expiration as an RFC 822-style Internet date string. Pass an empty string
+   * for no expiration. |
+   *
+   * | `etag` |  | Optional ETag or application metadata. Pass an empty string when unused. |
+   *
+   * | `bd` |  | The `BinData` containing the bytes to save. |
+   *
+   * **Expiration is not automatic deletion:** An expired item remains present until it is replaced
+   * or explicitly removed. This permits stale-while-revalidate workflows but requires the
+   * application to check freshness.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Cache.lastErrorText}.
+   */
+  saveBd(key: string, expiration: string, etag: string, bd: BinData): void
+}