Runtime SDK

Пакет @onreza/runtime предоставляет типизированный доступ к платформенным API из серверного кода. SDK работает в обоих рантаймах — Edge Functions и Compute Apps (Next.js, Astro SSR, любые Bun-приложения). API идентичен вне зависимости от рантайма. SDK состоит из отдельных модулей — импортируйте только то, что нужно.

Установка

npm

npm install @onreza/runtime

pnpm

pnpm add @onreza/runtime

yarn

yarn add @onreza/runtime

bun

bun add @onreza/runtime

KV Store

import { kv, isKVAvailable } from '@onreza/runtime/kv';

// Запись с TTL (секунды)
await kv.set('session:123', { userId: '456' }, { ttl: 3600 });

// Чтение (text по умолчанию, json, arrayBuffer)
const user = await kv.get('user:123', { type: 'json' });

// Проверка существования
const exists = await kv.has('user:123');

// Удаление
await kv.delete('session:123');

// Список ключей с пагинацией
const { keys, cursor } = await kv.list({ prefix: 'user:', limit: 50 });

Типы: KVStore, KVGetOptions, KVSetOptions, KVListOptions, KVListResult

→ Подробнее: KV Store

D1 Database

import { db, isDBAvailable } from '@onreza/runtime/db';

// Prepare → bind → execute
const { results } = await db.prepare('SELECT * FROM users WHERE id = ?')
  .bind(1)
  .all();

// Первая строка
const user = await db.prepare('SELECT * FROM users WHERE id = ?')
  .bind(1)
  .first();

// Insert/Update
await db.prepare('INSERT INTO users (name) VALUES (?)')
  .bind('Alice')
  .run();

// Batch (атомарная транзакция)
await db.batch([
  db.prepare('UPDATE accounts SET balance = balance - ? WHERE id = ?').bind(100, 1),
  db.prepare('UPDATE accounts SET balance = balance + ? WHERE id = ?').bind(100, 2),
]);

// DDL
await db.exec('CREATE TABLE IF NOT EXISTS logs (id INTEGER PRIMARY KEY, message TEXT)');

Методы PreparedStatement: .bind(), .all(), .first(), .run(), .raw()

Типы: D1Database, D1PreparedStatement, D1Result, D1Meta

→ Подробнее: D1 Database

Request Context

import { getContext, getClientIp, getGeo, getRequestId, isContextAvailable } from '@onreza/runtime/context';

// Полный контекст
const ctx = getContext();
// ctx.clientIp      — IP клиента
// ctx.geo.country   — ISO 3166-1 alpha-2 ("RU")
// ctx.geo.city      — город
// ctx.geo.region    — регион edge-ноды
// ctx.deploymentId  — ID деплоя
// ctx.projectId     — ID проекта
// ctx.commitSha     — Git SHA (short)
// ctx.requestId     — UUID v7

// Шорткаты
const ip = getClientIp();
const geo = getGeo();
const requestId = getRequestId();

Типы: OnrezaContext, OnrezaGeo

Environment Variables

import { env, isEnvAvailable, getEnv } from '@onreza/runtime/env';

// Получить переменную
const apiKey = env.get('API_KEY');       // string | undefined

// Получить с дефолтом
const timeout = getEnv('TIMEOUT', '5000'); // string (гарантированно)

// Проверить существование
if (env.has('DEBUG')) { /* ... */ }

// Итерация по всем переменным
for (const [key, value] of env.entries()) {
  console.log(`${key}=${value}`);
}

Совет

env.get() предпочтительнее process.env — более эффективная реализация и лучшая типизация.

Типы: EnvStore

→ Подробнее: Environment Variables

Image Optimization

import { imageUrl, generateSrcset, DEFAULT_SIZES } from '@onreza/runtime/image';

// Генерация URL
const url = imageUrl('/images/hero.jpg', { width: 1080 });
// → '/_onreza/image?url=%2Fimages%2Fhero.jpg&w=1080&q=75'

// С параметрами
const optimized = imageUrl('/images/photo.jpg', {
  width: 640,
  quality: 80,
  format: 'webp',
  fit: 'cover',
  blur: 10,
  dpr: 2,
});

// Responsive srcset
const srcset = generateSrcset('/images/photo.jpg', [640, 1080, 1920], { quality: 80 });
// → '/_onreza/image?...&w=640 640w, /_onreza/image?...&w=1080 1080w, ...'

// DEFAULT_SIZES = [640, 750, 828, 1080, 1200, 1920, 2048, 3840]

Опции: width, height, quality (1-100), format ('webp' | 'avif'), fit ('cover' | 'contain' | 'fill'), blur (0-250), dpr (1-5)

Безопасность: SDK автоматически отклоняет абсолютные URL, path traversal, и нормализует значения (ширина привязывается к ближайшему из DEFAULT_SIZES).

Типы: ImageTransformOptions, ImageFormat, ImageFit

→ Подробнее: Image Optimization

Проверки доступности

Каждый модуль экспортирует функцию is*Available() для проверки, доступен ли API в текущем окружении:

import { isKVAvailable } from '@onreza/runtime/kv';
import { isDBAvailable } from '@onreza/runtime/db';
import { isContextAvailable } from '@onreza/runtime/context';
import { isEnvAvailable } from '@onreza/runtime/env';

// Полезно для условного кода, который может выполняться вне ONREZA Runtime
if (isKVAvailable()) {
  const cached = await kv.get('data');
}

Заметка

Если вызвать метод SDK вне ONREZA Runtime (например, при серверном билде), будет выброшена ошибка с описанием. Используйте is*Available() для graceful degradation.

Типы

Для глобальных типов (автокомплит ONREZA.*) добавьте reference в tsconfig.json или в файл:

/// <reference types="@onreza/runtime/types" />

Или импортируйте конкретные типы:

import type { KVStore, D1Database, OnrezaContext, EnvStore } from '@onreza/runtime/types';

Использование в Compute Apps

SDK работает не только в Edge Functions, но и в Compute Apps — Next.js, Astro SSR, любых Bun-приложениях. API полностью идентичен.

Next.js App Router

app/api/data/route.ts

import { kv } from '@onreza/runtime/kv';
import { db } from '@onreza/runtime/db';

export async function GET() {
  const cached = await kv.get('homepage-data', { type: 'json' });
  if (cached) return Response.json(cached);

  const result = await db.prepare('SELECT * FROM products LIMIT 10').all();
  await kv.set('homepage-data', JSON.stringify(result.results), { ttl: 300 });
  return Response.json(result.results);
}

Astro SSR

src/pages/api/products.ts

import { db } from '@onreza/runtime/db';

export const prerender = false;

export async function GET() {
  const { results } = await db.prepare('SELECT * FROM products').all();
  return new Response(JSON.stringify(results), {
    headers: { 'Content-Type': 'application/json' },
  });
}

Как это работает

SDK — это тонкие типизированные обёртки над платформенными API, которые инжектируются в runtime. Transport выбирается автоматически в зависимости от окружения:

• Edge Functions (nrz-isolate): Native FFI — прямой вызов Rust, ~0us overhead
• Compute Apps (nrz-compute): HTTP over Unix socket, ~0.3ms overhead per call

Под капотом:

// SDK автоматически выбирает transport:
// Edge Functions → globalThis.ONREZA.kv (Native FFI)
// Compute Apps  → HTTP запросы через Unix socket
export const kv = resolveTransport().kv;
export const db = resolveTransport().db;

SDK даёт:

• Tree-shaking — импортируйте только нужные модули
• TypeScript типы — полный автокомплит и проверка типов
• Проверки доступности — is*Available() вместо ручных проверок
• Утилиты — imageUrl(), generateSrcset(), getEnv() с дефолтами
• Единый API — один и тот же код работает в Edge Functions и Compute Apps

Совместимость с рантаймами

Окружение	KV Store	D1 Database	Context	Env	Image	Transport
Edge Functions (nrz-isolate)	Полная	Полная	Полная	Полная	Полная	Native FFI
Compute Apps (nrz-compute)	Полная	Полная	Полная	Полная	Полная	HTTP (Unix socket)
nrz dev (эмулятор)	Полная	Полная	Полная	Полная	Полная	Эмуляция
Node.js / Bun (вне ONREZA)	—	—	—	—	—	Только с is*Available()

См. также

• Edge Runtime — Web APIs и ограничения Edge Runtime
• Compute Apps — Next.js, Astro SSR и другие Bun-приложения
• KV Store — key-value хранилище
• D1 Database — SQL база данных
• Image Optimization — оптимизация изображений