Schema Sheets

A multiwriter peer-to-peer schema-driven simple database built on Hyperdb. Schema Sheets provides a lightweight time series database where users can query by date ranges and apply JMESPath expressions for flexible data filtering.

Features

• Multiwriter P2P: Multiple peers can write to the same database simultaneously
• Schema-driven: Define JSON schemas to validate your data structure
• Time series support: Built-in time indexing for efficient date range queries
• JMESPath queries: Powerful JSON querying and filtering capabilities
• Decentralized: No central server required, data is replicated across peers

Installation

npm install schema-sheets

Quick Start

Joining an Existing Room

If you have a room link, you can quickly join and start adding data:

import schemasheets from 'schema-sheets'
import z32 from 'z32'
import corestore from 'corestore'

// decode room link to get keys
const decoded = z32.decode(roomlink)
const key = decoded.subarray(0, 32)
const encryptionkey = decoded.subarray(32)
const store = new corestore(path)

// create schemasheets instance
const sheets = new schemasheets(store, key, { encryptionkey })

await sheets.ready()
await sheets.join('your-username')

// now you can add data to existing schemas
const schemas = await sheets.listschemas()
if (schemas.length > 0) {
  await sheets.addRow(schemas[0].schemaId, { name: 'John', age: 30 })
}

API Reference

Schema Management

addNewSchema(name, jsonSchema)

Create a new schema with validation rules.

const schemaId = await sheets.addNewSchema('users', {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' },
    email: { type: 'string', format: 'email' }
  },
  required: ['name', 'email']
})

updateSchema(schemaId, jsonSchema)

Update an existing schema's validation rules.

const success = await sheets.updateSchema(schemaId, {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' },
    email: { type: 'string', format: 'email' },
    city: { type: 'string' } // new field
  },
  required: ['name', 'email']
})

renameSchema(schemaId, name)

Rename an existing schema.

const success = await sheets.renameSchema(schemaId, 'customers')

listSchemas()

Get all available schemas.

const schemas = await sheets.listSchemas()
// Returns: [{ schemaId, name, jsonSchema }, ...]

Row Management

addRow(schemaId, json, time?)

Add a new data row. Data is validated against the schema. Time is optional, set to Date.now(), but will be used for date queries later.

const success = await sheets.addRow(schemaId, {
  name: 'John Doe',
  age: 30,
  email: '[email protected]'
}, new Date('2024-01-15').getTime()) // optional timestamp

updateRow(uuid, json)

Update an existing row by UUID.

const success = await sheets.updateRow(rowUuid, {
  name: 'John Smith',
  age: 31,
  email: '[email protected]'
})

deleteRow(uuid)

Delete a row by UUID.

const success = await sheets.deleteRow(rowUuid)

Querying Data

list(schemaId, options)

Query rows with time range filtering and JMESPath expressions.

// Basic query
const rows = await sheets.list(schemaId)

// Time range query
const recentRows = await sheets.list(schemaId, {
  gte: Date.now() - (7 * 24 * 60 * 60 * 1000), // last 7 days
  lte: Date.now()
})

// JMESPath filtering
const adults = await sheets.list(schemaId, {
  gte: Date.now() - (7 * 24 * 60 * 60 * 1000), // last 7 days
  lte: Date.now()
  query: '[?age >= `18`]' // Only users 18 or older
})

// Complex JMESPath query
const emailDomains = await sheets.list(schemaId, {
  query: '[].{name: name, domain: split(email, `@`)[1]}'
})

JMESPath Query Examples

Schema Sheets supports powerful JMESPath queries for data filtering and transformation:

// Filter by condition
'[?age > `25`]'

// Select specific fields
'[].{name: name, email: email}'

// Complex filtering and transformation
'[?age >= `18` && contains(email, `gmail`)].{name: name, domain: split(email, `@`)[1]}'

Example Client

For a complete example implementation, see schema-sheets-cli which provides a command-line interface for all Schema Sheets operations.

License

MIT