Skip to main content
TinyCloud provides a key-value storage API for persisting user data. All data is stored in the user’s space and fully controlled by them.

​
Basic Operations

​
Put

Store a value at a key. 
await tc.storage.put('user/profile', {
  name: 'Alice',
  email: '[email protected]',
});

​
Get

Retrieve a value by key. 
const profile = await tc.storage.get('user/profile');
console.log(profile);
// { name: 'Alice', email: '[email protected]' }

​
List

List keys matching a prefix. 
const keys = await tc.storage.list('user/');
console.log(keys);
// ['user/profile', 'user/settings', 'user/preferences']

​
Delete

Remove a key and its value. 
await tc.storage.delete('user/profile');

​
Data Types

The KV API supports multiple data types. 
await tc.storage.put('greeting', 'Hello, World!');

const greeting = await tc.storage.get('greeting');
// "Hello, World!"

​
Organizing with Prefixes

Use path-like keys to organize data logically. 
// User data
await tc.storage.put('user/profile', { name: 'Alice' });
await tc.storage.put('user/settings', { theme: 'dark' });

// App data
await tc.storage.put('app/cache/items', [...]);
await tc.storage.put('app/state', { lastSync: Date.now() });

// Documents
await tc.storage.put('documents/2024/report.json', { ... });
await tc.storage.put('documents/2024/summary.json', { ... });

// List all documents from 2024
const docs = await tc.storage.list('documents/2024/');

​
Metadata

Store and retrieve metadata alongside values. 
// Put with metadata
await tc.storage.put('document', content, {
  metadata: {
    author: 'Alice',
    version: '1.0',
    createdAt: new Date().toISOString(),
  },
});

// Get metadata only (without fetching value)
const meta = await tc.storage.getMetadata('document');
console.log(meta);
// { author: 'Alice', version: '1.0', createdAt: '2024-...' }

​
Error Handling

Handle common error cases. 
try {
  const value = await tc.storage.get('nonexistent-key');
} catch (error) {
  if (error.code === 'NOT_FOUND') {
    console.log('Key does not exist');
  } else if (error.code === 'UNAUTHORIZED') {
    console.log('Session expired or invalid');
  } else {
    console.error('Unexpected error:', error);
  }
}

​
Practical Examples

​
User Preferences

// Save preferences
await tc.storage.put('preferences', {
  theme: 'dark',
  fontSize: 14,
  notifications: {
    email: true,
    push: false,
  },
});

// Load preferences with defaults
const prefs = await tc.storage.get('preferences') ?? {
  theme: 'light',
  fontSize: 12,
  notifications: { email: true, push: true },
};

​
Shopping Cart

// Add item to cart
async function addToCart(item) {
  const cart = await tc.storage.get('cart') ?? [];
  cart.push(item);
  await tc.storage.put('cart', cart);
}

// Clear cart
async function clearCart() {
  await tc.storage.delete('cart');
}

​
Document History

// Save document with version
async function saveDocument(docId, content) {
  const version = Date.now();

  // Save current version
  await tc.storage.put(`docs/${docId}/current`, content);

  // Save to history
  await tc.storage.put(`docs/${docId}/history/${version}`, content);
}

// List document history
async function getDocumentHistory(docId) {
  return await tc.storage.list(`docs/${docId}/history/`);
}