Merge pull request evoluhq#609 from evoluhq/add-owner-usage-tracking

Add owner usage tracking [in progress]

Author: steida

.changeset/kind-jars-lay.md

@@ -0,0 +1,25 @@
+---
+"@evolu/common": patch
+"@evolu/nodejs": patch
+"@evolu/react-native": patch
+"@evolu/react-web": patch
+---
+
+Add owner usage tracking and storage improvements
+
+### Breaking Changes
+
+- Renamed `TransportConfig` to `OwnerTransport` and `WebSocketTransportConfig` to `OwnerWebSocketTransport` for clearer naming
+- Renamed `SqliteStorageBase` to `BaseSqliteStorage` and `createSqliteStorageBase` to `createBaseSqliteStorage`
+- Extracted storage table creation into separate functions: `createBaseSqliteStorageTables` and `createRelayStorageTables` to support serverless deployments where table setup must be separate from storage operations
+- Removed `assertNoErrorInCatch` - it was unnecessary
+
+### Features
+
+- **Owner usage tracking** (in progress): Added `evolu_usage` table and `OwnerUsage` interface to track data consumption metrics per owner (stored bytes, received bytes, sent bytes, first/last timestamps). Table structure is in place but not yet fully implemented
+- **Timestamp privacy documentation**: Added privacy considerations explaining that timestamps are metadata visible to relays, with guidance on implementing local write queues for maximum privacy
+- **React Native polyfills**: Added polyfills for `AbortSignal.any()` and `AbortSignal.timeout()` to support Task cancellation on React Native platforms that don't yet implement these APIs
+
+### Performance
+
+- **isSqlMutation optimization**: Added LRU cache (10,000 entries) to `isSqlMutation` function, restoring Timestamp insert benchmark from 34k back to 57k inserts/sec.

.changeset/shy-planes-report.md

@@ -0,0 +1,29 @@
+---
+"@evolu/common": patch
+---
+
+Evolu identicons
+
+Added `createIdenticon` function for generating visually distinct SVG identicons from Evolu `Id` (including branded IDs like `OwnerId`, etc.). For user avatars, visual identity markers, and differentiating entities in UI without storing images.
+
+### Features
+
+- **Multiple styles**: Choose from 4 styles:
+  - `"github"` (default): 5×5 grid with horizontal mirroring, inspired by GitHub avatars
+  - `"quadrant"`: 2×2 color block grid with direct RGB mapping
+  - `"gradient"`: Diagonal stripe pattern with smooth color gradients
+  - `"sutnar"`: Ladislav Sutnar-inspired compositional design with adaptive colors
+- **SVG output**: Returns SVG string that can be used directly
+
+### Example
+
+```ts
+import { createIdenticon } from "@evolu/common";
+
+// Basic usage with default GitHub style
+const svg = createIdenticon(userId);
+
+const quadrant = createIdenticon(ownerId, "quadrant");
+const gradient = createIdenticon(postId, "gradient");
+const sutnar = createIdenticon(teamId, "sutnar");
+```

.changeset/strict-jokes-tie.md

@@ -0,0 +1,22 @@
+---
+"@evolu/common": patch
+---
+
+Add Cache module with generic cache interface and LRU cache implementation
+
+- New `Cache<K, V>` interface with `has`, `get`, `set`, `delete` methods
+- New `createLruCache` factory function for creating LRU caches with configurable capacity
+- Keys are compared by reference (standard Map semantics)
+- LRU cache automatically evicts least recently used entries when capacity is reached
+- Both `get` and `set` operations update access order
+- Exposes readonly `map` property for iteration and inspection
+
+Example:
+
+```ts
+const cache = createLruCache<string, number>(2);
+cache.set("a", 1);
+cache.set("b", 2);
+cache.set("c", 3); // Evicts "a"
+cache.has("a"); // false
+```

.github/copilot-instructions.md

@@ -179,7 +179,7 @@ const formatCurrencyCodeError = createTypeErrorFormatter<CurrencyCodeError>(
 - Use for catching developer mistakes eagerly (e.g., invalid configuration)
 
 ```ts
-import { assert, assertNonEmptyArray, assertNoErrorInCatch } from "./Assert.js";
+import { assert, assertNonEmptyArray } from "./Assert.js";
 
 // ✅ Good example
 const length = buffer.getLength();

.gitignore

@@ -15,3 +15,4 @@ storybook-static
 .direnv
 .eslintcache
 out
+test-identicons

apps/relay/package.json

@@ -7,7 +7,7 @@
     "dev": "node --experimental-strip-types --watch src/index.ts",
     "build": "shx rm -rf dist && tsc",
     "start": "node dist/index.js",
-    "clean": "shx rm -rf .turbo node_modules dist db.sqlite",
+    "clean": "shx rm -rf .turbo node_modules dist data/evolu-relay.db",
     "docker:build": "docker-compose build --no-cache",
     "docker:up": "docker-compose up --build",
     "docker:up:detached": "docker-compose up -d --build",

apps/relay/src/index.ts

@@ -16,8 +16,8 @@ const relay = await createNodeJsRelay({
    * ### Example
    *
    * ```ts
-   * Evolu.createWebSocketTransportConfig({
-   *   relayUrl: "ws://localhost:4000",
+   * Evolu.createOwnerWebSocketTransport({
+   *   url: "ws://localhost:4000",
    *   ownerId: "6jy_2F4RT5qqeLgJ14_dnQ" as Evolu.OwnerId,
    * });
    * ```

apps/web/src/app/(landing)/blog/the-copy-paste-typescript-standard-library/page.mdx

@@ -86,7 +86,7 @@ It’s half a joke and half the truth. Programmers should understand the code th
 
 - [Result](https://github.com/evoluhq/evolu/blob/main/packages/common/src/Result.ts) (type‑safe errors)
 - [Brand](https://github.com/evoluhq/evolu/blob/main/packages/common/src/Brand.ts) (prevents mixing incompatible values, e.g., `type UserId = string & Brand<"UserId">`)
-- [Assert](https://github.com/evoluhq/evolu/blob/main/packages/common/src/Assert.ts) (fail‑fast helpers: `assert`, `assertNonEmptyArray`, `assertNoErrorInCatch`)
+- [Assert](https://github.com/evoluhq/evolu/blob/main/packages/common/src/Assert.ts) (fail‑fast helpers: `assert`, `assertNonEmptyArray`)
 - [Array](https://github.com/evoluhq/evolu/blob/main/packages/common/src/Array.ts) (non‑empty arrays and helpers: `NonEmptyArray`, `isNonEmptyArray`, `appendToArray`)
 - [Function](https://github.com/evoluhq/evolu/blob/main/packages/common/src/Function.ts) (small function utils: `exhaustiveCheck`, `identity`, `LazyValue`)
 - [Object](https://github.com/evoluhq/evolu/blob/main/packages/common/src/Object.ts) (object helpers: `isPlainObject`, `mapObject`, `objectToEntries`, `excludeProp`)

examples/react-expo/app/index.tsx

@@ -1,13 +1,13 @@
+import Alert from "@blazejkustra/react-native-alert";
+import type { Evolu as EvoluType } from "@evolu/common";
 import * as Evolu from "@evolu/common";
 import { createUseEvolu, EvoluProvider, useQuery } from "@evolu/react";
+import { EvoluIdenticon } from "@evolu/react-native";
 import {
   evoluReactNativeDeps,
   localAuth,
-  EvoluAvatar,
 } from "@evolu/react-native/expo-sqlite";
 import { FC, Suspense, use, useEffect, useMemo, useState } from "react";
-import type { Evolu as EvoluType } from "@evolu/common";
-
 import {
   ActivityIndicator,
   ScrollView,
@@ -18,7 +18,6 @@ import {
   View,
 } from "react-native";
 import { SafeAreaView } from "react-native-safe-area-context";
-import Alert from "@blazejkustra/react-native-alert";
 
 // Namespace for the current app (scopes databases, passkeys, etc.)
 const service = "rn-expo";
@@ -97,15 +96,15 @@ export default function Index(): React.ReactNode {
   );
 }
 
-function EvoluDemo({
+const EvoluDemo = ({
   evolu,
   ownerIds,
   authResult,
 }: {
   evolu: EvoluType<typeof Schema>;
   ownerIds: Array<Evolu.AuthList> | null;
   authResult: Evolu.AuthResult | null;
-}): React.ReactNode {
+}): React.ReactNode => {
   const useEvolu = createUseEvolu(evolu);
 
   // Evolu uses Kysely for type-safe SQL (https://kysely.dev/).
@@ -501,7 +500,7 @@ function EvoluDemo({
     return (
       <View style={styles.ownerProfileRow}>
         <View style={styles.ownerInfo}>
-          <EvoluAvatar id={ownerId} />
+          <EvoluIdenticon id={ownerId} />
           <View style={styles.ownerDetails}>
             <Text style={styles.ownerUsername}>{username}</Text>
             <Text
@@ -577,7 +576,7 @@ function EvoluDemo({
       </ScrollView>
     </SafeAreaView>
   );
-}
+};
 
 const styles = StyleSheet.create({
   container: {

examples/react-vite-pwa/src/components/EvoluMinimalExample.tsx

@@ -1,6 +1,6 @@
 import * as Evolu from "@evolu/common";
 import { createUseEvolu, EvoluProvider, useQuery } from "@evolu/react";
-import { evoluReactWebDeps, EvoluAvatar, localAuth } from "@evolu/react-web";
+import { evoluReactWebDeps, EvoluIdenticon, localAuth } from "@evolu/react-web";
 import { IconEdit, IconTrash } from "@tabler/icons-react";
 import clsx from "clsx";
 import { FC, Suspense, use, useMemo, useState } from "react";
@@ -415,7 +415,7 @@ const OwnerProfile: FC<{
   return (
     <div className="flex justify-between gap-3">
       <div className="flex items-center gap-3">
-        <EvoluAvatar id={ownerId} />
+        <EvoluIdenticon id={ownerId} />
         <span className="text-sm font-medium text-gray-900">{username}</span>
         <span className="text-xs text-gray-500 italic">{ownerId}</span>
       </div>