SqlSandbox (TypeScript SDK)

Cliente TypeScript para consumir el servicio local de sandboxes DuckDB por HTTP.

Este SDK esta pensado para frontend, pero tambien funciona en Node.js moderno (usa fetch).

Instalacion

npm install "@sfperusac/sqlsandbox"

Uso Basico

import { SqlSandbox } from "@sfperusac/sqlsandbox"

const sb = new SqlSandbox()

await sb.loadTable("ventas", [
  { id: 1, total: 100 },
  { id: 2, total: 200 }
])

const result = await sb.query<{ total: number }>(
  "SELECT SUM(total) as total FROM ventas"
)

console.log(result.toObjects())
// [{ total: 300 }]

await sb.destroy()

Playground (cliente manual)

Hay un playground listo para ejecutar contra el backend local:

cd sdk-typescript
npm run playground

Esto corre examples/playground/run.mjs y muestra:

• create sandbox (lazy)
• loadTable
• listTables
• queries con agregaciones y JOIN
• destroy

Configuracion

Defaults internos:

{
  baseUrl: "http://localhost:1323",
  autoDestroy: true,
  timeoutMs: 60000
}

Config global (afecta instancias nuevas):

SqlSandbox.configure({
  baseUrl: "http://localhost:9999",
  timeoutMs: 30000
})

Override por instancia:

const sb = new SqlSandbox({ timeoutMs: 5000 })

Resolucion final (merge shallow):

final = { ...DEFAULTS, ...GLOBAL, ...INSTANCE }

Metodos

loadTable(name, data, options?)

• data es un array de objetos.
• Infere columnas en orden estable: keys del primer objeto, luego nuevas keys al final.
• Tipos inferidos si no se entrega schema.
• schema puede ser parcial.

Reglas importantes:

• Si una fila no tiene un campo, se envia null.
• Si en una misma columna aparecen tipos inconsistentes (ej. string y number), lanza error.
• Identificadores (tabla/columnas) se validan con ^[a-zA-Z_][a-zA-Z0-9_]*$.

type Venta = { id: number; total: number; createdAt: Date }

await sb.loadTable<Venta>("ventas", ventas, {
  schema: {
    id: "INTEGER",
    total: "DOUBLE",
    createdAt: "TIMESTAMP"
  }
})

query(sql, options?)

const r = await sb.query<{ id: number; total: number }>(
  "SELECT id, total FROM ventas ORDER BY id",
  { limit: 100, offset: 0 }
)

const rows = r.toObjects() // tipado

listTables()

const tables = await sb.listTables()

destroy()

• Idempotente.
• Luego de destroy(), cualquier uso lanza SqlSandboxError.

Concurrencia

La instancia serializa operaciones (cola interna). No se ejecutan dos operaciones simultaneas.

Auto Destroy

Si autoDestroy=true y existe window, registra beforeunload para intentar borrar el sandbox al cerrar pagina.

Errores

El SDK lanza SqlSandboxError.

Campos:

• code
• status (si viene del backend)

Errores backend:

{ "error": { "code": "SQL_NOT_ALLOWED", "message": "..." } }

El SDK convierte esto a SqlSandboxError con:

• code = error.code
• status = HTTP status

Errores locales (ejemplos):

• SANDBOX_DESTROYED
• INVALID_TABLE_NAME / INVALID_COLUMN_NAME
• INVALID_REQUEST (data vacia, tipos inconsistentes, etc)
• TIMEOUT
• NETWORK_ERROR

Endpoints Usados

El SDK utiliza estos endpoints del backend:

• POST /sandboxes
• POST /sandboxes/{id}/tables
• GET /sandboxes/{id}/tables
• POST /sandboxes/{id}/query
• DELETE /sandboxes/{id}