Entity TypeScript ORM

The @expo/entity-secondary-cache-local-memory package provides a cross-request secondary cache for @expo/entity using an LRU (Least Recently Used) strategy.

Warning: This cache is shared between requests within the same Node.js process and is considered nonstandard. Use it with caution.

To implement it, you must:

1. Create a concrete implementation of the EntitySecondaryCacheLoader abstract class.
2. Instantiate your loader with a LocalMemorySecondaryEntityCache.
3. Provide an LRU cache instance via GenericLocalMemoryCacher.createLRUCache.

import { 
  LocalMemorySecondaryEntityCache, 
  GenericLocalMemoryCacher 
} from '@expo/entity-secondary-cache-local-memory';

// 1. Implementation of EntitySecondaryCacheLoader (e.g., TestSecondaryLocalMemoryCacheLoader)
// 2. Instantiate with LocalMemorySecondaryEntityCache and an LRU cache
const secondaryCacheLoader = new TestSecondaryLocalMemoryCacheLoader(
  new LocalMemorySecondaryEntityCache(
    GenericLocalMemoryCacher.createLRUCache<LocalMemoryTestEntityFields>({}),
  ),
  LocalMemoryTestEntity.loader(viewerContext),
);

// 3. Load entities
const loadParams = { id: createdEntity.getID() };
const results = await secondaryCacheLoader.loadManyAsync([loadParams]);

Unlike traditional authorization patterns where you load data and then manually check permissions (which is error-prone), Entity combines data loading and authorization into a single step.

You define a PrivacyPolicy for your model containing rules (e.g., readRules). When you request data using a loader initialized with a ViewerContext, the framework automatically applies these rules to ensure the viewer has permission to access the requested object before returning it.

Conceptual Example

class PhotoPrivacyPolicy {
  // Define which rules allow a user to read a photo
  readRules = [new AllowIfOwnerRule(), new AllowIfOrganizationPermissionRule()];
}

// In your application logic (e.g., a view or controller)
async function get_photo_page(viewer: ViewerContext): Promise<string> {
  // The loader is initialized with the viewer's context
  // Authorization is performed automatically during the load
  const photo = await PhotoEntity.loader(viewer).loadById(id);
  return render_html(photo);
}

class PhotoPrivacyPolicy {
  readRules = [new AllowIfOwnerRule(), new AllowIfOrganizationPermissionRule()];
}

// in the view, for example
async function get_photo_page(viewer: ViewerContext): string {
  const photo = await PhotoEntity.loader(viewer).loadById(id);
  return render_html(photo);
}

The @expo/entity-database-adapter-knex package provides a Knex-based database adapter for @expo/entity. Currently, this adapter is only supported when using the pg (Postgres) client.

To use it, you must instantiate a knex instance with a Postgres connection and then provide it to the EntityCompanionProvider by mapping the postgres flavor to the PostgresEntityDatabaseAdapter and its corresponding PostgresEntityQueryContextProvider.

import { knex, Knex } from 'knex';

// 1. Create your Knex instance (Postgres only)
const knexInstance = knex({
  client: 'pg',
  connection: {
    user: process.env['PGUSER'],
    password: process.env['PGPASSWORD'],
    host: process.env['PGHOST'],
    port: parseInt(process.env['PGPORT']!, 10),
    database: process.env['PGDATABASE'],
  },
});

// 2. Register the adapter during EntityCompanionProvider instantiation
export const createDefaultEntityCompanionProvider = (
  metricsAdapter: IEntityMetricsAdapter = new NoOpEntityMetricsAdapter()
): EntityCompanionProvider => {
  return new EntityCompanionProvider(
    metricsAdapter,
    {
      // add the knex database adapter flavor
      ['postgres']: {
        adapter: PostgresEntityDatabaseAdapter,
        queryContextProvider: new PostgresEntityQueryContextProvider(knexInstance),
      },
    },
    {
      // ... other options
    }
  );
};

To use Redis as a cache for @expo/entity, you must provide a RedisCacheAdapterProvider within the configuration object passed to the EntityCompanionProvider constructor. This adapter uses ioredis under the hood.

When configuring the RedisCacheAdapterProvider, you need to provide a context object containing:

• redisClient: An instance of ioredis.
• cacheKeyDelimiter: A string used to separate parts of the cache key.
• cacheKeyPrefix: A string prefix for all cache keys.
• ttlSecondsPositive: TTL in seconds for positive cache entries.
• ttlSecondsNegative: TTL in seconds for negative cache entries.

import Redis from 'ioredis';
import { EntityCompanionProvider } from '@expo/entity';
import { RedisCacheAdapterProvider } from '@expo/entity-cache-adapter-redis';

const genericRedisCacherContext = {
  redisClient: new Redis(new URL(process.env['REDIS_URL']!).toString()),
  cacheKeyDelimiter: ':',
  cacheKeyPrefix: 'ent-',
  ttlSecondsPositive: 86400, // 1 day
  ttlSecondsNegative: 600, // 10 minutes
};

export const createDefaultEntityCompanionProvider = (
  metricsAdapter: IEntityMetricsAdapter = new NoOpEntityMetricsAdapter()
): EntityCompanionProvider => {
  return new EntityCompanionProvider(
    metricsAdapter,
    {
      // ... other EntityCompanionProvider options
    },
    {
      ['redis']: {
        cacheAdapterProvider: new RedisCacheAdapterProvider(genericRedisCacherContext),
      },
    }
  );
};