T87s Core

https://github.com/t87s/core
Admin
T87s Core is a caching library that provides mechanisms to query, invalidate, and manage cached...
Tokens:34,713
Snippets:139
Trust Score:7.5
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install and Start t87s Demo

Source: https://github.com/t87s/core/blob/main/examples/demo/README.md

Installs project dependencies using pnpm and starts the t87s demo application. This is the primary command to run the example.

```bash
pnpm install
pnpm start
```

--------------------------------

### Quickstart: Using Primitives with TypeScript

Source: https://github.com/t87s/core/blob/main/README.md

Illustrates how to use the raw Primitives API from @t87s/core for direct cache operations. This example shows initializing Primitives with a MemoryAdapter and performing a query with key and tags.

```typescript
import { createPrimitives, MemoryAdapter } from '@t87s/core';

const p = createPrimitives({ adapter: new MemoryAdapter() });

await p.query({
  key: 'users:123',
  tags: [['users', '123']],
  fn: () => db.users.findById('123'),
});
```

--------------------------------

### Install @t87s/core Package

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/getting-started.mdx

Installs the @t87s/core library using common package managers like npm, yarn, pnpm, deno, pip, and uv. The 'snail' tab provides a humorous, non-functional installation method.

```bash
npm install @t87s/core
```

```bash
yarn add @t87s/core
```

```bash
pnpm add @t87s/core
```

```bash
pip install t87s
```

```bash
uv add t87s
```

--------------------------------

### First Query with QueryCache in Python

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/getting-started.mdx

Illustrates how to set up a QueryCache in Python using AsyncMemoryAdapter, defining tag schemas and a cached method for retrieving user data. It also shows how to invalidate a query.

```python
from t87s import QueryCache, TagSchema, Wild, cached
from t87s.adapters import AsyncMemoryAdapter

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

class Users(TagSchema):
    settings: WildTagSchema]
    posts: Wild"Posts"]

class Posts(TagSchema):
    comments: WildTagSchema]

class Cache(QueryCacheTags]):
    @cached(Tags.users())
    async def get_user(self, id: str):
        return await db.users.find_by_id(id)

cache = Cache(adapter=AsyncMemoryAdapter())

await cache.get_user("123")
await cache.invalidate(cache.t.users("123"))
```

--------------------------------

### Import QueryCache in Deno

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/getting-started.mdx

Demonstrates how to import the QueryCache class from the @t87s/core library within a Deno environment using npm specifiers.

```typescript
import { QueryCache } from "npm:@t87s/core";
```

--------------------------------

### First Query with QueryCache in TypeScript

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/getting-started.mdx

Shows how to define a schema, initialize a QueryCache with a MemoryAdapter, and perform a basic query for user data. It also includes an example of invalidating a query based on tags.

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

const schema = at('users', () =>
  wild.at('settings').at('posts', () => wild.at('comments', () => wild))
);

const cache = QueryCache({
  schema,
  adapter: new MemoryAdapter(),
  queries: (tags) => ({
    getUser: (id: string) => ({
      tags: tags.users(id)],
      fn: () => db.users.findById(id),
    }),
  }),
});

await cache.getUser('123');
await cache.invalidate(cache.tags.users('123'));
```

--------------------------------

### Install @t87s/core

Source: https://github.com/t87s/core/blob/main/README.md

Installs the @t87s/core package using npm. This is the first step to using the library in your project.

```bash
npm install @t87s/core
```

--------------------------------

### Quickstart: Using QueryCache with TypeScript

Source: https://github.com/t87s/core/blob/main/README.md

Demonstrates how to set up and use the QueryCache API from @t87s/core. It shows schema definition, cache initialization with a MemoryAdapter, defining a getUser query, invalidating cache entries, and accessing cache metadata.

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

const schema = at('users', () => wild.at('settings'));

const cache = QueryCache({
  schema,
  adapter: new MemoryAdapter(),
  queries: (tags) => ({
    getUser: (id: string) => ({
      tags: [tags.users(id)],
      fn: () => db.users.findById(id),
    }),
  }),
});

await cache.getUser('123');
await cache.invalidate(cache.tags.users('123'));

// Access cache metadata via .entries
const result = await cache.getUser('123').entries;
console.log(result.before); // CacheEntry | null (null on miss)
console.log(result.after); // CacheEntry (always present)
```

--------------------------------

### Core Caching Operations with Primitives (Python)

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/primitives.mdx

Illustrates essential caching functionalities using t87s core primitives in Python. This example shows how to initialize primitives with an asynchronous memory adapter, configure default TTL and grace periods, and execute query, set, get, invalidate, and delete actions.

```python
from t87s import create_primitives
from t87s.adapters import AsyncMemoryAdapter

p = create_primitives(
    adapter=AsyncMemoryAdapter(),
    default_ttl="30s",
    default_grace="2m",
)

# Query: fetch if not cached, cache the result
await p.query(
    key="users:123",
    tags=[("users", "123")],
    fn=lambda: db.users.find_by_id("123"),
)

# Set: manually cache a value
await p.set(
    "users:settings",
    settings,
    tags=[("users", "settings")],
    ttl="10m",
)

# Get: read without recomputing
user = await p.get("users:123")

# Invalidate: mark tags as stale
await p.invalidate([("users", "123")])

# Delete: remove from cache entirely
await p.delete("users:settings")

```

--------------------------------

### Initialize t87s with RedisAdapter (TypeScript, Python)

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/concepts/adapters.mdx

Shows how to set up t87s with the RedisAdapter for self-hosted production environments. This adapter requires a running Redis instance and specific environment variables for connection. The Python version requires installing `t87s[redis]`.

```typescript
import { RedisAdapter } from '@t87s/core';
import { Redis } from '@upstash/redis';

const t87s = new T87s({
  adapter: new RedisAdapter({
    client: new Redis({
      url: process.env.UPSTASH_REDIS_REST_URL,
      token: process.env.UPSTASH_REDIS_REST_TOKEN,
    }),
  }),
});
```

```python
import os
import redis
from t87s import T87s
from t87s.adapters.redis import RedisAdapter

# pip install t87s[redis]
client = redis.Redis.from_url(os.environ["REDIS_URL"])
t87s = T87s(adapter=RedisAdapter(client))
```

--------------------------------

### Test Primitives API Initialization

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

This test verifies that the `createPrimitives` function correctly exposes the expected methods (get, set, del, invalidate) when initialized with a storage adapter.

```typescript
// src/primitives.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { createPrimitives } from './primitives.js';
import { MemoryAdapter } from './adapters/index.js';

describe('Primitives', () => {
  it('exposes get/set/del/invalidate', async () => {
    const adapter = new MemoryAdapter();
    const primitives = createPrimitives({ adapter });

    expect(primitives.get).toBeDefined();
    expect(primitives.set).toBeDefined();
    expect(primitives.del).toBeDefined();
    expect(primitives.invalidate).toBeDefined();
  });
});
```

--------------------------------

### Initialize t87s with CloudAdapter (TypeScript, Python)

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/concepts/adapters.mdx

Provides examples for initializing t87s with the CloudAdapter, a managed caching solution with a free tier. It leverages AI for real-time cache optimization and requires an API key set via environment variables. The Python version requires `t87s[cloud]`.

```typescript
import { CloudAdapter } from '@t87s/core';

const t87s = new T87s({
  adapter: new CloudAdapter({
    apiKey: process.env.T87S_API_KEY,
  }),
});
```

```python
import os
from t87s import T87s
from t87s.adapters.cloud import CloudAdapter

# pip install t87s[cloud]
t87s = T87s(adapter=CloudAdapter(api_key=os.environ["T87S_API_KEY"]))

```

--------------------------------

### Set and Invalidate Cache with Tags (JavaScript)

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

Demonstrates setting a cache entry with specific tags and then invalidating it using those tags. The 'get' operation after invalidation should return null.

```javascript
await primitives.set('key1', { foo: 'bar' }, { tags: [['posts', '1']], ttl: '1m' });
    await primitives.invalidate([['posts', '1']]);
    const result = await primitives.get('key1');
    expect(result).toBeNull();
```

--------------------------------

### Initialize T87s Query Cache (TypeScript, Python)

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/cloud.mdx

Demonstrates how to initialize the T87s QueryCache with a schema, adapter, and query definitions. Supports both TypeScript and Python, showing equivalent setup for cache initialization and query definition.

```typescript
import { QueryCache, at, wild, CloudAdapter } from '@t87s/core';

const cache = QueryCache({
  schema: at('users', () => wild),
  adapter: new CloudAdapter({ apiKey: process.env.T87S_API_KEY! }),
  queries: (tags) => ({
    getUser: (id: string) => ({
      tags: [tags.users(id)],
      fn: () => db.users.findById(id),
    }),
  }),
});
```

```python
import os
from t87s import QueryCache, TagSchema, Wild, cached
from t87s.adapters import AsyncCloudAdapter

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

class Cache(QueryCache[Tags]):
    @cached(Tags.users())
    async def get_user(self, id: str):
        return await db.users.find_by_id(id)

cache = Cache(adapter=AsyncCloudAdapter(api_key=os.environ["T87S_API_KEY"])).
```

--------------------------------

### Use and Invalidate Cache with t87s

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/query-cache/tutorial.mdx

Demonstrates how to fetch data using the t87s cache, which automatically handles caching and re-fetching on cache misses. Includes examples of invalidating cached data based on specific tags to ensure data freshness. Supports TypeScript and Python.

```typescript
// These hit the database the first time, cache after that
await cache.getUser('123');
await cache.getPost('123', 'p1');

// User 123 changed? Invalidate everything under that tag
await cache.invalidate(cache.tags.users('123'));

// Next call to getUser('123') will re-fetch

```

```python
# These hit the database the first time, cache after that
await cache.get_user("123")
await cache.get_post("123", "p1")

# User 123 changed? Invalidate everything under that tag
await cache.invalidate(cache.t.users("123"))

# Next call to get_user("123") will re-fetch

```

--------------------------------

### Get or Fetch Data from Cache

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

Retrieves data from the cache. If the data is fresh and valid, it's returned directly. If stale, it checks the grace period. If expired or no grace period, it fetches and caches new data. Includes optional verification of fresh cache hits.

```typescript
private async getOrFetch<T>(cacheKey: string, options: QueryOptions<T>): Promise<T> {
    const now = Date.now();

    const cached = await this.adapter.get<T>(cacheKey);
    if (cached) {
      const isStale = await this.isEntryStale(cached);

      if (!isStale && cached.expiresAt > now) {
        // Fresh hit
        if (this.shouldVerify()) {
          this.runVerification(cacheKey, options.fn, cached.value).catch(() => {});
        }
        return cached.value;
      }

      // Check grace period (SWR)
      if (cached.graceUntil !== null && cached.graceUntil > now) {
        this.refreshInBackground(cacheKey, options);
        return cached.value;
      }
    }

    return await this.fetchAndCache(cacheKey, options, cached ?? undefined);
  }
```

--------------------------------

### Cache Invalidation with Prefix Matching (Python)

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/concepts/prefix-matching.mdx

Illustrates cache invalidation with prefix matching in Python using @t87s. This example defines a tag schema and demonstrates how invalidating a user tag cascades to their associated posts and settings tags.

```python
from t87s import QueryCache, TagSchema, Wild, Static, cached
from t87s.adapters import AsyncMemoryAdapter

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

class Users(TagSchema):
    posts: Static
    settings: Static

class Cache(QueryCache[Tags]):
    @cached(Tags.users())
    async def get_user(self, id: str):
        return await db.users.find_by_id(id)

    @cached(Tags.users().posts)
    async def get_user_posts(self, id: str):
        return await db.posts.find_by_user_id(id)

    @cached(Tags.users().settings)
    async def get_user_settings(self, id: str):
        return await db.settings.find_by_user_id(id)

cache = Cache(adapter=AsyncMemoryAdapter())

# Invalidating cache.t.users("123") also invalidates:
# - ("users", "123")             ← exact match
# - ("users", "123", "posts")    ← prefix match
# - ("users", "123", "settings") ← prefix match
await cache.invalidate(cache.t.users("123"))
```

--------------------------------

### Define Cached Queries with Python

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/query-cache/query-definitions.mdx

Illustrates how to define cached queries using Python with the t87s QueryCache. It shows the setup of a TagSchema, defining cached methods with decorators, and configuring the adapter and default cache settings. The example also demonstrates calling the defined cache methods.

```python
from t87s import QueryCache, TagSchema, Wild, cached
from t87s.adapters import AsyncMemoryAdapter

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

class Cache(QueryCache[Tags]):
    @cached(Tags.users())
    async def get_user(self, id: str):
        return await db.users.find_by_id(id)

    @cached(Tags.users(), ttl="30s")  # override the default
    async def get_user_with_posts(self, id: str):
        return await db.users.find_by_id_with_posts(id)

cache = Cache(
    adapter=AsyncMemoryAdapter(),
    default_ttl="1m",
    default_grace="5m",
)

# Now use those methods do...
await cache.get_user("123") # get a user
await cache.get_user_with_posts("123") # get their posts
```

--------------------------------

### Run Vitest Tests (Shell)

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

This command executes the Vitest test suite for the tag builder runtime. It ensures that all tests, including the tag creation logic, pass successfully.

```shell
pnpm vitest run src/tag-builder.test.ts
```

--------------------------------

### Implement Low-Level Cache Operations with createPrimitives API

Source: https://context7.com/t87s/core/llms.txt

Illustrates using the createPrimitives function for direct cache control with manual key management. This is suitable for custom key schemes or ad-hoc caching. The example covers querying with stampede protection, retrieving cache metadata, manually setting and getting data, invalidating entries by tags (hierarchical and exact), deleting specific keys, and managing the cache lifecycle.

```typescript
import { createPrimitives, MemoryAdapter } from '@t87s/core';

const cache = createPrimitives({
  adapter: new MemoryAdapter(),
  prefix: 'myapp',
  defaultTtl: '30s',
  defaultGrace: '5m',
  verifyPercent: 0.1, // Sample 10% of cache hits for verification
});

// Query: fetch if not cached, cache the result with stampede protection
const user = await cache.query({
  key: 'user:123',
  tags: [['users', '123']],
  fn: async () => {
    const response = await fetch('https://api.example.com/users/123');
    return response.json();
  },
  ttl: '10m',
  grace: '1h',
});

// Query with entries for cache metadata
const result = await cache.queryWithEntries({
  key: 'user:456',
  tags: [['users', '456']],
  fn: () => fetchUser('456'),
});
console.log(result.before); // null on miss, CacheEntry on hit
console.log(result.after.value); // The cached/fetched data

// Manual set: cache arbitrary data
await cache.set('computed:daily-stats', { total: 1000, active: 250 }, {
  tags: [['stats', 'daily']],
  ttl: '1h',
  grace: '6h',
});

// Manual get: retrieve without recomputing
const stats = await cache.get<{ total: number; active: number }>('computed:daily-stats');

// Invalidate by tags (hierarchical)
await cache.invalidate([['users', '123']]); // Invalidates all users:123:* entries

// Exact invalidation (no cascade to children)
await cache.invalidate([['users', '123']], true);

// Delete specific key
await cache.del('computed:daily-stats');

// Clear all cached data
await cache.clear();

// Disconnect adapter
await cache.disconnect();

```

--------------------------------

### Cache Engine Query with TTL and Grace Handling (JavaScript)

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

Demonstrates querying the cache engine with Time-To-Live (TTL) and grace period settings. It shows how stale data is returned while a background refresh occurs and how errors are handled during background refreshes.

```javascript
const fn = vi.fn(async () => ({ count: ++callCount }));

    // First call
    await engine.query({ key: 'test', tags: [['test']], fn, ttl: 1, grace: 10000 });

    // Wait for TTL to expire
    await new Promise(r => setTimeout(r, 10));

    // Should return stale value (count: 1) while refreshing in background
    const result = await engine.query({ key: 'test', tags: [['test']], fn, ttl: 1, grace: 10000 });
    expect(result.count).toBe(1);

    // Wait for background refresh
    await new Promise(r => setTimeout(r, 50));

    // Now should have fresh value
    const result2 = await engine.query({ key: 'test', tags: [['test']], fn, ttl: 1, grace: 10000 });
    expect(result2.count).toBe(2);
  });

  it('error handling with grace returns stale on failure', async () => {
    let callCount = 0;
    const fn = vi.fn(async () => {
      callCount++;
      if (callCount > 1) throw new Error('fail');
      return { count: callCount };
    });

    // First call succeeds
    await engine.query({ key: 'test', tags: [['test']], fn, ttl: 1, grace: 10000 });

    // Wait for TTL
    await new Promise(r => setTimeout(r, 10));

    // Invalidate to force refetch
    await engine.invalidate([['test']]);

    // Should return graced value even though fn throws
    const result = await engine.query({ key: 'test', tags: [['test']], fn, ttl: 1, grace: 10000 });
    expect(result.count).toBe(1);
  });
```

--------------------------------

### Running Cache Engine Tests (Bash)

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

Command to execute all tests for the cache engine using the pnpm and vitest test runner.

```bash
pnpm vitest run src/cache-engine.test.ts
```

--------------------------------

### Start t87s Demo with Redis (Upstash)

Source: https://github.com/t87s/core/blob/main/examples/demo/README.md

Starts the t87s demo application using Upstash Redis for caching. Requires setting UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN environment variables.

```bash
UPSTASH_REDIS_REST_URL=... UPSTASH_REDIS_REST_TOKEN=... pnpm start:redis
```

--------------------------------

### Cache Expiration by TTL (JavaScript)

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

Demonstrates that cache entries expire after their specified Time-To-Live (TTL). A 'get' operation after the TTL has passed will return null.

```javascript
await primitives.set('key1', { foo: 'bar' }, { tags: [['test']], ttl: 1 }); // 1ms
    await new Promise(r => setTimeout(r, 10));
    const result = await primitives.get('key1');
    expect(result).toBeNull();
```

--------------------------------

### Run Vitest Tests (Bash)

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

Command to execute the tests defined in the primitives.test.ts file using the Vitest test runner.

```bash
pnpm vitest run src/primitives.test.ts
```

--------------------------------

### Test Primitives API Functionality

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

These tests cover the core functionalities of the Primitives API, including setting and getting values, handling missing keys, deleting values, and invalidating cached data using tags.

```typescript
// Add to src/primitives.test.ts

describe('Primitives', () => {
  let adapter: MemoryAdapter;
  let primitives: ReturnType<typeof createPrimitives>;

  beforeEach(() => {
    adapter = new MemoryAdapter();
    primitives = createPrimitives({ adapter });
  });

  it('set and get value', async () => {
    await primitives.set('key1', { foo: 'bar' }, { tags: [['test']], ttl: '1m' });
    const result = await primitives.get<{ foo: string }>('key1');
    expect(result).toEqual({ foo: 'bar' });
  });

  it('returns null for missing key', async () => {
    const result = await primitives.get('nonexistent');
    expect(result).toBeNull();
  });

  it('del removes value', async () => {
    await primitives.set('key1', { foo: 'bar' }, { tags: [['test']], ttl: '1m' });
    await primitives.del('key1');
    const result = await primitives.get('key1');
    expect(result).toBeNull();
  });

  it('invalidate makes value return null', async () => {

```

--------------------------------

### Verify Exports with TypeScript Import

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

This TypeScript code snippet demonstrates a quick sanity check to verify that exports from the './dist/index.js' file are working correctly. It imports various components, including QueryCache, at, wild, createPrimitives, and MemoryAdapter, to ensure they are accessible.

```typescript
import { QueryCache, at, wild, createPrimitives, MemoryAdapter } from './dist/index.js';
```

--------------------------------

### Testing Schema Builders (at, wild) in TypeScript

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

This snippet demonstrates unit tests for the 'at' and 'wild' schema builder functions. It verifies the correct construction of schema objects, including nested structures and sibling relationships, using the Vitest testing framework.

```typescript
// Add to src/schema.test.ts

it('at() with children', () => {
  const schema = at('posts', () => wild);
  expect(schema._tag).toBe('at');
  expect(schema._children._tag).toBe('wild');
});

it('wild as terminal value', () => {
  expect(wild._tag).toBe('wild');
});

it('wild() with children', () => {
  const schema = wild(() => at('comments'));
  expect(schema._tag).toBe('wild');
  expect(schema._children._tag).toBe('at');
});

it('chaining at() for siblings', () => {
  const schema = at('posts').at('users');
  expect(schema._tag).toBe('at');
  expect(schema._name).toBe('posts');
});

it('complex nested schema', () => {
  const schema = at('posts', () =>
    wild(() => at('comments', () => wild)).at('settings')
  ).at('history');
  expect(schema._tag).toBe('at');
  expect(schema._name).toBe('posts');
});
```

--------------------------------

### Initialize t87s with MemoryAdapter (TypeScript, Python)

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/concepts/adapters.mdx

Demonstrates how to initialize the t87s client using the MemoryAdapter. This adapter is suitable for local development as it offers single-process, non-persistent storage. It requires no external dependencies.

```typescript
import { MemoryAdapter } from '@t87s/core';

const t87s = new T87s({
  adapter: new MemoryAdapter(),
});
```

```python
from t87s import T87s, MemoryAdapter

t87s = T87s(adapter=MemoryAdapter())
```

--------------------------------

### Committing Cache Engine Changes (Bash)

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

Commands to stage and commit the cache engine source and test files using git.

```bash
git add src/cache-engine.ts src/cache-engine.test.ts
git commit -m "feat: extract CacheEngine from T87s with all features"
```

--------------------------------

### Hierarchical Tag Invalidation Example - TypeScript

Source: https://context7.com/t87s/core/llms.txt

Demonstrates setting up a QueryCache with hierarchical tags and performing various invalidation operations. It shows how invalidating a parent tag cascades to children and how to use exact mode for specific tag invalidation.

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

const cache = QueryCache({
  schema: at('orgs', () =>
    wild(() =>
      at('projects', () => wild.at('tasks', () => wild))
        .at('members', () => wild)
        .at('settings')
    )
  ),
  adapter: new MemoryAdapter(),
  queries: (tags) => ({
    getOrg: (id: string) => ({
      tags: [tags.orgs(id)],
      fn: () => db.orgs.findById(id),
    }),
    getProject: (orgId: string, projectId: string) => ({
      tags: [tags.orgs(orgId).projects(projectId)],
      fn: () => db.projects.findById(projectId),
    }),
    getTask: (orgId: string, projectId: string, taskId: string) => ({
      tags: [tags.orgs(orgId).projects(projectId).tasks(taskId)],
      fn: () => db.tasks.findById(taskId),
    }),
    getOrgSettings: (orgId: string) => ({
      tags: [tags.orgs(orgId).settings],
      fn: () => db.settings.findByOrgId(orgId),
    }),
  }),
});

// Populate cache
await cache.getOrg('acme');
await cache.getProject('acme', 'website');
await cache.getTask('acme', 'website', 'task-1');
await cache.getOrgSettings('acme');

// Hierarchical invalidation: invalidates org AND all nested data
await cache.invalidate(cache.tags.orgs('acme'));
// Invalidated: orgs:acme, orgs:acme:projects:*, orgs:acme:settings, etc.

// Invalidate just a project (and its tasks)
await cache.invalidate(cache.tags.orgs('acme').projects('website'));
// Invalidated: orgs:acme:projects:website, orgs:acme:projects:website:tasks:*

// Exact invalidation: only the specified tag, no cascade
await cache.invalidate(cache.tags.orgs('acme').projects('website'), true);
// Invalidated: only orgs:acme:projects:website (tasks remain valid)
```

--------------------------------

### Implement Tag Builder Logic

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

This is the core implementation of the tag builder. It includes functions to create tags, build tags from 'at' and 'wild' schema nodes, and handle sibling nodes. It uses unique symbols for type safety and recursively builds the tag structure.

```typescript
// src/tag-builder.ts
import type { AtNode, WildNode, AtBuilder, WildBuilder } from './schema.js';
import type { TypedTag, SchemaToTags } from './query-cache-types.js';

declare const TAG_BRAND: unique symbol;

function createTag(path: string[]): TypedTag {
  return {
    [TAG_BRAND]: true as const,
    __path: path,
  } as TypedTag;
}

type SchemaNode = AtBuilder<string, any, any> | AtNode<string, any, any> | WildBuilder<any, any> | WildNode<any, any>;

function buildTagsFromAt(schema: AtNode<string, any, any> | AtBuilder<string, any, any>, currentPath: string[]): any {
  const path = [...currentPath, schema._name];
  const tag = createTag(path);

  let childTags = {};
  if (schema._children && typeof schema._children === 'object' && '_tag' in schema._children) {
    if (schema._children._tag === 'at') {
      childTags = buildTagsFromAt(schema._children, path);
    } else if (schema._children._tag === 'wild') {
      childTags = buildTagsFromWild(schema._children, path);
    }
  }

  let siblingTags = {};
  if (schema._siblings && typeof schema._siblings === 'object') {
    siblingTags = buildSiblings(schema._siblings, currentPath);
  }

  return {
    [schema._name]: Object.assign(tag, childTags),
    ...siblingTags,
  };
}

function buildTagsFromWild(schema: WildNode<any, any> | WildBuilder<any, any>, currentPath: string[]): any {
  const wildFn = (id: string) => {
    const path = [...currentPath, id];
    const tag = createTag(path);

    let childTags = {};
    if (schema._children && typeof schema._children === 'object' && '_tag' in schema._children) {
      if (schema._children._tag === 'at') {
        childTags = buildTagsFromAt(schema._children, path);
      } else if (schema._children._tag === 'wild') {
        childTags = buildTagsFromWild(schema._children, path);
      }
    }

    return Object.assign(tag, childTags);
  };

  // Make the function itself also a tag (for the path without ID)
  Object.assign(wildFn, createTag(currentPath));

  let siblingTags = {};
  if (schema._siblings && typeof schema._siblings === 'object') {
    siblingTags = buildSiblings(schema._siblings, currentPath);
  }

  return Object.assign(wildFn, siblingTags);
}

function buildSiblings(siblings: any, currentPath: string[]): any {
  const result: any = {};

  for (const [key, value] of Object.entries(siblings)) {
    if (value && typeof value === 'object' && '_tag' in value) {
      const node = value as SchemaNode;
      if (node._tag === 'at') {
        Object.assign(result, buildTagsFromAt(node as AtNode<string, any, any>, currentPath));
      } else if (node._tag === 'wild') {
        Object.assign(result, buildTagsFromWild(node as WildNode<any, any>, currentPath));
      }
    }
  }

  return result;
}

export function createTagBuilder<S>(schema: S): SchemaToTags<S> {
  const s = schema as unknown as SchemaNode;
  if (s._tag === 'at') {
    return buildTagsFromAt(s as AtNode<string, any, any>, []) as SchemaToTags<S>;
  } else if (s._tag === 'wild') {
    return buildTagsFromWild(s as WildNode<any, any>, []) as SchemaToTags<S>;
  }
  return {} as SchemaToTags<S>;
}
```

--------------------------------

### Cache Invalidation with Prefix Matching (TypeScript)

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/concepts/prefix-matching.mdx

Demonstrates how to set up a cache schema and invalidate tags using prefix matching in TypeScript. This example shows how invalidating a user tag also invalidates their posts and settings tags.

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

const schema = at('users', () =>
  wild.at('posts').at('settings')
);

const cache = QueryCache({
  schema,
  adapter: new MemoryAdapter(),
  queries: (tags) => ({
    getUser: (id: string) => ({
      tags: [tags.users(id)],
      fn: () => db.users.findById(id),
    }),
    getUserPosts: (id: string) => ({
      tags: [tags.users(id).posts],
      fn: () => db.posts.findByUserId(id),
    }),
    getUserSettings: (id: string) => ({
      tags: [tags.users(id).settings],
      fn: () => db.settings.findByUserId(id),
    }),
  }),
});

// Invalidating cache.tags.users('123') also invalidates:
// - ['users', '123']           ← exact match
// - ['users', '123', 'posts']  ← prefix match
// - ['users', '123', 'settings'] ← prefix match
await cache.invalidate(cache.tags.users('123'));
```

--------------------------------

### Query Cache Data - Python

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/query-cache/cache-metadata.mdx

This snippet shows a basic cache query in Python, retrieving user data. Similar to the TypeScript example, it doesn't expose the cache's internal state, highlighting the need for the `.entries` property.

```python
user = await cache.get_user("123")
# user is User, but was this from cache? Fresh? Stale?
```

--------------------------------

### Configure Cache TTL in Python

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/concepts/ttl.mdx

Illustrates how to define a Time To Live (TTL) for cached asynchronous functions in Python using the T87s library. This example caches user retrieval for 10 minutes, utilizing the `@cached` decorator with a specified TTL.

```python
from t87s import QueryCache, TagSchema, Wild, cached
from t87s.adapters import AsyncMemoryAdapter

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

class Cache(QueryCache[Tags]):
    @cached(Tags.users(), ttl="10m")  # Cache this for 10 minutes
    async def get_user(self, id: str):
        return await db.users.find_by_id(id)

cache = Cache(adapter=AsyncMemoryAdapter())
```

--------------------------------

### Create Query Cache with t87s

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/query-cache/tutorial.mdx

Initialize a QueryCache instance with your defined schema and an adapter (e.g., MemoryAdapter). Define cacheable queries with their associated tags and data fetching functions. Supports TypeScript and Python.

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

const cache = QueryCache({
  schema,
  adapter: new MemoryAdapter(),
  queries: (tags) => ({
    getUser: (id: string) => ({
      tags: [tags.users(id)],
      fn: () => db.users.findById(id),
    }),
    getPost: (userId: string, postId: string) => ({
      tags: [tags.users(userId).posts(postId)],
      fn: () => db.posts.findById(postId),
    }),
  }),
});

```

```python
from t87s import QueryCache, cached
from t87s.adapters import AsyncMemoryAdapter

class Cache(QueryCache[Tags]):
    @cached(Tags.users())
    async def get_user(self, id: str):
        return await db.users.find_by_id(id)

    @cached(Tags.users().posts())
    async def get_post(self, user_id: str, post_id: str):
        return await db.posts.find_by_id(post_id)

cache = Cache(adapter=AsyncMemoryAdapter())

```

--------------------------------

### Implement Primitives API

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

This is the core implementation of the Primitives API. It defines the `createPrimitives` function which returns an object with methods for interacting with a storage adapter. It handles key prefixing, expiration, grace periods, and tag-based invalidation.

```typescript
// src/primitives.ts
import type { StorageAdapter, CacheEntry } from './types.js';
import { parseDuration, type Duration } from './duration.js';

export interface PrimitivesOptions {
  adapter: StorageAdapter;
  prefix?: string;
}

export interface SetOptions {
  tags: string[][];
  ttl: Duration;
  grace?: Duration | false;
}

export interface Primitives {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T, options: SetOptions): Promise<void>;
  del(key: string): Promise<void>;
  invalidate(tags: string[][], exact?: boolean): Promise<void>;
  clear(): Promise<void>;
  disconnect(): Promise<void>;
}

export function createPrimitives(options: PrimitivesOptions): Primitives {
  const adapter = options.adapter;
  const prefix = options.prefix ?? 't87s';

  const prefixKey = (key: string) => `${prefix}:${key}`;

  return {
    async get<T>(key: string): Promise<T | null> {
      const entry = await adapter.get<T>(prefixKey(key));
      if (!entry) return null;

      const now = Date.now();

      // Check if expired
      if (entry.expiresAt <= now) {
        // Check grace
        if (entry.graceUntil === null || entry.graceUntil <= now) {
          return null;
        }
      }

      // Check tag invalidation
      for (const tag of entry.tags) {
        for (let len = 1; len <= tag.length; len++) {
          const prefix = tag.slice(0, len);
          const invalidation = await adapter.getTagInvalidationTime(prefix);
          if (invalidation !== null && invalidation >= entry.createdAt) {
            return null;
          }
        }
        // Check exact
        const exactTag = [...tag, '__exact__'];
        const exactInvalidation = await adapter.getTagInvalidationTime(exactTag);
        if (exactInvalidation !== null && exactInvalidation >= entry.createdAt) {
          return null;
        }
      }

      return entry.value;
    },

    async set<T>(key: string, value: T, setOptions: SetOptions): Promise<void> {
      const ttl = parseDuration(setOptions.ttl);
      const grace = setOptions.grace === false ? false : parseDuration(setOptions.grace ?? '0');
      const now = Date.now();

      const entry: CacheEntry<T> = {
        value,
        tags: setOptions.tags,
        createdAt: now,
        expiresAt: now + ttl,
        graceUntil: grace === false ? null : now + ttl + grace,
      };

      await adapter.set(prefixKey(key), entry);
    },

    async del(key: string): Promise<void> {
      await adapter.delete(prefixKey(key));
    },

    async invalidate(tags: string[][], exact = false): Promise<void> {
      const now = Date.now();
      for (const tag of tags) {
        if (exact) {
          const exactTag = [...tag, '__exact__'];
          await adapter.setTagInvalidationTime(exactTag, now);
        } else {
          await adapter.setTagInvalidationTime(tag, now);
        }
      }
    },

    async clear(): Promise<void> {
      await adapter.clear();
    },

    async disconnect(): Promise<void> {
      await adapter.disconnect();
    },
  };
}
```

--------------------------------

### Commit Changes (Bash)

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

Git commands to stage and commit the modified primitives.ts and primitives.test.ts files with a descriptive commit message.

```bash
git add src/primitives.ts src/primitives.test.ts
git commit -m "feat: add primitives API (get/set/del/invalidate)"
```

--------------------------------

### Configure Cache TTL in TypeScript

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/concepts/ttl.mdx

Demonstrates how to set a Time To Live (TTL) for cached queries using the T87s Core library in TypeScript. This example caches user data for 10 minutes, ensuring that the data is re-fetched from the database after this period.

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

const cache = QueryCache({
  schema: at('users', () => wild),
  adapter: new MemoryAdapter(),
  queries: (tags) => ({
    getUser: (id: string) => ({
      tags: [tags.users(id)],
      ttl: '10m', // Cache this for 10 minutes
      fn: () => db.users.findById(id),
    }),
  }),
});
```

--------------------------------

### Problem: Cache Refresh Failure Without Grace Period (Python)

Source: https://github.com/t87s/core/blob/main/docs/src/content/docs/concepts/grace-periods.mdx

Presents a Python example where the cache fails to update due to a database outage. This code highlights the issue of users receiving errors after the Time-To-Live (TTL) expires if no grace period is configured.

```python
from t87s import QueryCache, TagSchema, Wild, cached
from t87s.adapters import AsyncMemoryAdapter

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

class Cache(QueryCache[Tags]):
    @cached(Tags.users(), ttl="10m")
    async def get_user(self, id: str):
        return await db.users.find_by_id(id)  # What if DB is down?

cache = Cache(adapter=AsyncMemoryAdapter())

```

--------------------------------

### Implement Schema Node Types and Builders

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

This TypeScript code defines the interfaces for schema node types ('AtNode', 'WildNode') and their corresponding builders ('AtBuilder', 'WildBuilder'). It includes runtime implementations for creating these nodes and builders, along with the public API functions 'at' and 'wild'.

```typescript
// src/schema.ts

// =============================================================================
// Schema Node Types (for type inference)
// =============================================================================

export interface AtNode<Name extends string = string, Children = never, Siblings = never> {
  readonly _tag: 'at';
  readonly _name: Name;
  readonly _children: Children;
  readonly _siblings: Siblings;
}

export interface WildNode<Children = never, Siblings = never> {
  readonly _tag: 'wild';
  readonly _children: Children;
  readonly _siblings: Siblings;
}

// =============================================================================
// Schema Builder Interfaces
// =============================================================================

export interface AtBuilder<Name extends string, Children, Siblings> extends AtNode<Name, Children, Siblings> {
  at<N extends string>(name: N): AtBuilder<Name, Children, Siblings | AtNode<N>>;
  at<N extends string, C>(name: N, child: () => C): AtBuilder<Name, Children, Siblings | AtNode<N, C>>;
}

export interface WildBuilder<Children, Siblings> extends WildNode<Children, Siblings> {
  at<N extends string>(name: N): WildBuilder<Children, Siblings | AtNode<N>>;
  at<N extends string, C>(name: N, child: () => C): WildBuilder<Children, Siblings | AtNode<N, C>>;
}

// =============================================================================
// Runtime Implementation
// =============================================================================

function createAtBuilder<Name extends string, Children, Siblings>(
  name: Name,
  children: Children,
  siblings: Siblings
): AtBuilder<Name, Children, Siblings> {
  return {
    _tag: 'at',
    _name: name,
    _children: children,
    _siblings: siblings,
    at: ((n: string, child?: () => unknown) => {
      const childValue = child ? child() : undefined;
      const newSibling = child
        ? { _tag: 'at' as const, _name: n, _children: childValue, _siblings: undefined as never }
        : { _tag: 'at' as const, _name: n, _children: undefined as never, _siblings: undefined as never };
      const mergedSiblings = siblings ? { ...siblings as object, [n]: newSibling } : { [n]: newSibling };
      return createAtBuilder(name, children, mergedSiblings as any);
    }) as AtBuilder<Name, Children, Siblings>['at'],
  };
}

function createWildBuilder<Children, Siblings>(
  children: Children,
  siblings: Siblings
): WildBuilder<Children, Siblings> {
  return {
    _tag: 'wild',
    _children: children,
    _siblings: siblings,
    at: ((n: string, child?: () => unknown) => {
      const childValue = child ? child() : undefined;
      const newSibling = child
        ? { _tag: 'at' as const, _name: n, _children: childValue, _siblings: undefined as never }
        : { _tag: 'at' as const, _name: n, _children: undefined as never, _siblings: undefined as never };
      const mergedSiblings = siblings ? { ...siblings as object, [n]: newSibling } : { [n]: newSibling };
      return createWildBuilder(children, mergedSiblings as any);
    }) as WildBuilder<Children, Siblings>['at'],
  };
}

// =============================================================================
// Public API
// =============================================================================

export function at<N extends string>(name: N): AtBuilder<N, never, never>;
export function at<N extends string, C>(name: N, child: () => C): AtBuilder<N, C, never>;
export function at<N extends string, C>(name: N, child?: () => C): AtBuilder<N, C, never> {
  const children = child ? child() : (undefined as never);
  return createAtBuilder(name, children, undefined as never);
}

export interface Wild extends WildBuilder<never, never> {
  <C>(child: () => C): WildBuilder<C, never>;
}

const wildImpl = function <C>(child?: () => C): WildBuilder<C, never> {
  const children = child ? child() : (undefined as never);
  return createWildBuilder(children, undefined as never)
} as Wild;

export const wild: Wild = Object.assign(wildImpl, {
  _tag: 'wild' as const,
  _children: undefined as never,
  _siblings: undefined as never,
  at: ((n: string, child?: () => unknown) => {
    const childValue = child ? child() : undefined;
    const newSibling = child
      ? { _tag: 'at' as const, _name: n, _children: childValue, _siblings: undefined as never }

```

--------------------------------

### Write Failing Test for CacheEngine

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

This TypeScript code defines the initial failing test for the CacheEngine. It sets up the testing environment using Vitest and imports necessary components like CacheEngine and MemoryAdapter. The test verifies that an engine instance can be created with an adapter.

```typescript
// src/cache-engine.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { CacheEngine } from './cache-engine.js';
import { MemoryAdapter } from './adapters/index.js';

describe('CacheEngine', () => {
  let adapter: MemoryAdapter;
  let engine: CacheEngine;

  beforeEach(() => {
    adapter = new MemoryAdapter();
    engine = new CacheEngine({ adapter });
  });

  it('creates engine with adapter', () => {
    expect(engine).toBeDefined();
  });
});
```

--------------------------------

### Commit Changes (Git)

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

This command stages and commits the changes made to the tag builder implementation and its corresponding test file. It uses a conventional commit message indicating a new feature.

```git
git add src/tag-builder.ts src/tag-builder.test.ts
git commit -m "feat: add tag builder runtime"
```

--------------------------------

### Commit Integration Test

Source: https://github.com/t87s/core/blob/main/docs/plans/2026-01-30-query-cache-implementation.md

Stages and commits the newly created integration test file for the QueryCache.

```bash
git add src/query-cache.integration.test.ts
git commit -m "test: integration test for full QueryCache workflow"

```
Tokens:
Raw