Schema

The basic job of any caching system is to store and retrieve unchanging data in a fast-to-access place until it goes stale, at which point it must be refreshed with up-to-data data.

Tags are how we communicate what data is stored. A schema, which you’ll learn about in this section, is how to construct those tags in t87s.

Scheming about schemas

A t87s schema is a tree-based structure that describes how tags work in your application. If you’ve defined a GraphQL or OpenAPI schema before, it should feel familiar, and hopefully even easier to construct.

Schemas have two kinds of segments: wild (dynamic IDs that change per entity) and static (fixed strings that are the same for everyone).

TypeScript

import { QueryCache, at, wild, MemoryAdapter } from '@t87s/core';

const schema = at('users', () =>
  wild
    .at('settings')  // static: all users share the same 'settings' concept
    .at('posts', () => wild.at('comments', () => wild))  // wild: each post has its own ID
);

const cache = QueryCache({
  schema,
  adapter: new MemoryAdapter(),
  queries: () => ({}),
});

// These all work:
cache.tags.users                                    // ['users']
cache.tags.users('123');                            // ['users', '123']
cache.tags.users.settings;                          // ['users', 'settings']
cache.tags.users('123').posts('p1');                // ['users', '123', 'posts', 'p1']
cache.tags.users('123').posts('p1').comments('c9'); // ['users', '123', 'posts', 'p1', 'comments', 'c9']

Python

from t87s import QueryCache, TagSchema, Wild, Static
from t87s.adapters import AsyncMemoryAdapter

class Tags(TagSchema):
    users: Wild["Users"]

class Users(TagSchema):
    settings: Static  # static: all users share the same 'settings' concept
    posts: Wild["Posts"]  # wild: each post has its own ID

class Posts(TagSchema):
    comments: Wild[TagSchema]

class Cache(QueryCache[Tags]):
    pass

cache = Cache(adapter=AsyncMemoryAdapter())

# These all work:
cache.t.users                                     # ('users',)
cache.t.users("123")                              # ('users', '123')
cache.t.users.settings                            # ('users', 'settings')
cache.t.users("123").posts("p1")                  # ('users', '123', 'posts', 'p1')
cache.t.users("123").posts("p1").comments("c9")   # ('users', '123', 'posts', 'p1', 'comments', 'c9')

You can think of tags as messages passed from invalidations, which mark data as stale, to queries, which fetch new data or return cached data. In the next section, we’ll learn what thes queries are.