Skip to main content

Managing Cache Values

The CacheService provides comprehensive methods for managing cache values programmatically, including fetching, setting, and clearing cache entries.

Quick Start​

import Ductape from '@ductape/sdk';

const ductape = new Ductape({
  accessKey: 'your-access-key',
});
const { caches } = ductape;

// Fetch cache values
const values = await caches.fetchValues({
  cache: 'user-cache',
});

// Get a specific value
const value = await cache.get({ key: 'user:123' });

// Set a value
await cache.set({
  cache: 'user-cache',
  key: 'user:123',
  value: JSON.stringify({ name: 'John' }),
});

// Clear a value
await cache.clear({ key: 'user:123' });

Fetching Cache Values​

Retrieve paginated cache values with optional filtering by environment:

const result = await caches.fetchValues({
  cache: 'user-cache',
  page: 1,
  limit: 20,
});

console.log('Total values:', result.total);
console.log('Total pages:', result.totalPages);

for (const value of result.values) {
  console.log('Key:', value.key);
  console.log('Value:', value.value);
  console.log('Expires:', value.expiry);
}

Parameters​

FieldTypeRequiredDescription
productstringYesThe tag of your product
cachestringYesThe tag of the cache
envstringNoFilter by environment
pagenumberNoPage number (default: 1)
limitnumberNoValues per page (default: 20)

Response​

{
  values: ICacheValue[];   // Array of cache values
  total: number;           // Total number of values
  page: number;            // Current page
  limit: number;           // Values per page
  totalPages: number;      // Total number of pages
}

Getting a Single Value​

Retrieve a specific cache value by its key:

const value = await cache.get({ key: 'user:123' });

if (value) {
  console.log('Found:', value.key);
  console.log('Data:', JSON.parse(value.value));
} else {
  console.log('Value not found');
}

Parameters​

FieldTypeRequiredDescription
keystringYesThe cache entry key

Response​

Returns ICacheValue | null:

{
  _id: string;           // Unique ID
  key: string;           // Cache key
  value: string;         // Cached value (stringified)
  cache_tag: string;     // Cache tag
  product_tag: string;   // Product tag
  component_tag: string; // Component tag
  component_type: string;// Component type
  expiry?: Date;         // Expiration date (if set)
  createdAt: Date;       // Creation timestamp
  updatedAt: Date;       // Last update timestamp
}

Setting Cache Values​

Store a value in the cache:

await cache.set({
  cache: 'user-cache',
  key: 'user:123',
  value: JSON.stringify({ name: 'John', email: 'john@example.com' }),
  expiry: new Date(Date.now() + 3600000), // 1 hour from now
});

Parameters​

FieldTypeRequiredDescription
productstringYesThe tag of your product
cachestringYesThe tag of the cache
keystringYesUnique key for this entry
valuestringYesThe value to cache (typically JSON)
componentTagstringNoComponent tag (defaults to cache tag)
componentTypestringNoComponent type (defaults to 'cache')
expiryDateNoExpiration date

Response​

Returns boolean indicating success.

Clearing Cache Values​

Clear a Single Value​

Remove a specific cache entry by key:

const cleared = await cache.clear({ key: 'user:123' });
console.log('Cleared:', cleared);

Clear All Values​

Remove all cache values for a product/cache combination:

const result = await caches.clearAll({
  cache: 'user-cache',
});

console.log('Cleared', result.cleared, 'values');

Fetching Dashboard Metrics​

Get comprehensive metrics about your cache:

const dashboard = await caches.fetchDashboard({
  cache: 'user-cache',
});

console.log('Total values:', dashboard.totalValues);
console.log('Active values:', dashboard.activeValues);
console.log('Expired values:', dashboard.expiredValues);
console.log('Total size:', dashboard.totalSize, 'bytes');

Response​

{
  totalValues: number;   // Total number of cached values
  activeValues: number;  // Non-expired values
  expiredValues: number; // Expired values
  totalSize: number;     // Total size in bytes
}

Complete Example​

Here's a complete example showing how to manage cache values:

import { CacheService } from '@ductape/sdk';

const cache = new CacheService({
  accessKey: 'your-access-key',
});

async function manageCacheValues() {
  const product = 'my-product';
  const cacheTag = 'user-cache';

  // Store some values
  await cache.set({
    product,
    cache: cacheTag,
    key: 'user:1',
    value: JSON.stringify({ name: 'Alice', role: 'admin' }),
    expiry: new Date(Date.now() + 86400000), // 24 hours
  });

  await cache.set({
    product,
    cache: cacheTag,
    key: 'user:2',
    value: JSON.stringify({ name: 'Bob', role: 'user' }),
    expiry: new Date(Date.now() + 86400000),
  });

  // Get dashboard metrics
  const dashboard = await cache.fetchDashboard({ product, cache: cacheTag });
  console.log('Cache Stats:', dashboard);

  // Fetch all values
  const result = await cache.fetchValues({ product, cache: cacheTag });
  console.log('Total values:', result.total);

  // Get a specific value
  const user = await cache.get({ key: 'user:1' });
  if (user) {
    console.log('User 1:', JSON.parse(user.value));
  }

  // Clear a value
  await cache.clear({ key: 'user:2' });

  // Clear all values
  const cleared = await cache.clearAll({ product, cache: cacheTag });
  console.log('Cleared', cleared.cleared, 'values');
}

manageCacheValues();

Error Handling​

All cache methods throw CacheError on failure:

import { CacheService, CacheError } from '@ductape/sdk';

try {
  const values = await cache.fetchValues({
    cache: 'user-cache',
  });
} catch (error) {
  if (error instanceof CacheError) {
    console.log('Error code:', error.code);
    console.log('Message:', error.message);
    // Codes: FETCH_VALUES_FAILED, FETCH_DASHBOARD_FAILED,
    //        GET_VALUE_FAILED, SET_VALUE_FAILED,
    //        CLEAR_VALUE_FAILED, CLEAR_VALUES_FAILED
  }
}

API Reference​

CacheService Methods​

MethodDescription
fetchValues()Get paginated cache values
fetchDashboard()Get cache metrics
get()Get a specific value by key
set()Store a value in the cache
clear()Clear a single value by key
clearAll()Clear all values for a product/cache

TypeScript Interfaces​

interface IFetchCacheValuesOptions {
  product: string;
  cache: string;
  env?: string;
  page?: number;
  limit?: number;
}

interface IFetchCacheDashboardOptions {
  product: string;
  cache: string;
  env?: string;
}

interface ISetCacheValueOptions {
  product: string;
  cache: string;
  key: string;
  value: string;
  componentTag?: string;
  componentType?: string;
  expiry?: Date;
}

interface IClearCacheValueOptions {
  key: string;
}

interface IClearCacheValuesOptions {
  product: string;
  cache: string;
  env?: string;
}

See Also​