CipherStash schema builder for TypeScript
npm install @cipherstash/schemaA TypeScript schema builder for CipherStash Protect.js that enables you to define encryption schemas with searchable encryption capabilities.
@cipherstash/schema is a standalone package that provides the schema building functionality used by @cipherstash/protect. While not required for basic Protect.js usage, this package is available if you need to build encryption configuration schemas directly or want to understand the underlying schema structure.
``bash`
npm install @cipherstash/schemaor
yarn add @cipherstash/schemaor
pnpm add @cipherstash/schema
`typescript
import { csTable, csColumn, buildEncryptConfig } from '@cipherstash/schema'
// Define your schema
const users = csTable('users', {
email: csColumn('email').freeTextSearch().equality().orderAndRange(),
name: csColumn('name').freeTextSearch(),
age: csColumn('age').orderAndRange(),
})
// Build the encryption configuration
const config = buildEncryptConfig(users)
console.log(config)
`
Creates a table definition with encrypted columns.
`typescript
import { csTable, csColumn } from '@cipherstash/schema'
const users = csTable('users', {
email: csColumn('email'),
name: csColumn('name'),
})
`
Creates a column definition with configurable indexes and data types.
`typescript
import { csColumn } from '@cipherstash/schema'
const emailColumn = csColumn('email')
.freeTextSearch() // Enable text search
.equality() // Enable exact matching
.orderAndRange() // Enable sorting and range queries
.dataType('string') // Set data type
`
Creates a value definition for nested objects (up to 3 levels deep).
`typescript
import { csTable, csColumn, csValue } from '@cipherstash/schema'
const users = csTable('users', {
email: csColumn('email').equality(),
profile: {
name: csValue('profile.name'),
address: {
street: csValue('profile.address.street'),
location: {
coordinates: csValue('profile.address.location.coordinates'),
},
},
},
})
`
Builds the final encryption configuration from table definitions.
`typescript
import { buildEncryptConfig } from '@cipherstash/schema'
const config = buildEncryptConfig(users, orders, products)
`
Enables exact matching queries.
`typescript`
const emailColumn = csColumn('email').equality()
// SQL equivalent: WHERE email = 'example@example.com'
Enables text search with configurable options.
`typescript`
const descriptionColumn = csColumn('description').freeTextSearch({
tokenizer: { kind: 'ngram', token_length: 3 },
token_filters: [{ kind: 'downcase' }],
k: 6,
m: 2048,
include_original: true,
})
// SQL equivalent: WHERE description LIKE '%example%'
Enables sorting and range queries.
`typescript`
const priceColumn = csColumn('price').orderAndRange()
// SQL equivalent: ORDER BY price ASC, WHERE price > 100
Set the data type for a column using .dataType():
`typescript`
const column = csColumn('field')
.dataType('string') // text (default)
.dataType('number') // Javascript number (i.e. integer or float)
.dataType('jsonb') // JSON binary
Support for nested object encryption (up to 3 levels deep):
`typescript`
const users = csTable('users', {
email: csColumn('email').equality(),
profile: {
name: csValue('profile.name'),
address: {
street: csValue('profile.address.street'),
city: csValue('profile.address.city'),
location: {
coordinates: csValue('profile.address.location.coordinates'),
},
},
},
})
> Note: Nested objects are not searchable and are not recommended for SQL databases. Use separate columns for searchable fields.
`typescript`
const column = csColumn('field').equality([
{ kind: 'downcase' }
])
`typescript`
const column = csColumn('field').freeTextSearch({
tokenizer: { kind: 'standard' },
token_filters: [{ kind: 'downcase' }],
k: 8,
m: 4096,
include_original: false,
})
The schema builder provides full TypeScript support:
`typescript
import { csTable, csColumn, type ProtectTableColumn } from '@cipherstash/schema'
const users = csTable('users', {
email: csColumn('email').equality(),
name: csColumn('name').freeTextSearch(),
} as const)
// TypeScript will infer the correct types
type UsersTable = typeof users
`
While this package can be used standalone, it's typically used through @cipherstash/protect:
`typescript
import { csTable, csColumn } from '@cipherstash/protect'
const users = csTable('users', {
email: csColumn('email').equality().freeTextSearch(),
})
const protectClient = await protect({
schemas: [users],
})
`
The buildEncryptConfig function generates a configuration object like this:
`typescript`
{
v: 2,
tables: {
users: {
email: {
cast_as: 'text',
indexes: {
unique: { token_filters: [] },
match: {
tokenizer: { kind: 'ngram', token_length: 3 },
token_filters: [{ kind: 'downcase' }],
k: 6,
m: 2048,
include_original: true,
},
ore: {},
},
},
},
},
}
- Standalone schema building: When you need to generate encryption configurations outside of Protect.js
- Custom tooling: Building tools that work with CipherStash encryption schemas
- Schema validation: Validating schema structures before using them with Protect.js
- Documentation generation: Creating documentation from schema definitions
Creates a table definition.
Parameters:
- tableName: The name of the table in the databasecolumns
- : Object defining the columns and their configurations
Returns: ProtectTable
Creates a column definition.
Parameters:
- columnName: The name of the column in the database
Returns: ProtectColumn
Methods:
- .dataType(castAs: CastAs): Set the data type.equality(tokenFilters?: TokenFilter[])
- : Enable equality index.freeTextSearch(opts?: MatchIndexOpts)
- : Enable text search.orderAndRange()
- : Enable order and range index.searchableJson()
- : Enable searchable JSON index
Creates a value definition for nested objects.
Parameters:
- valueName: Dot-separated path to the value (e.g., 'profile.name')
Returns: ProtectValue
Methods:
- .dataType(castAs: CastAs): Set the data type
Builds the encryption configuration.
Parameters:
- ...tables: Variable number of table definitions
Returns: EncryptConfig`
MIT License - see LICENSE.md for details.