Skip to main content Link Search Menu Expand Document (external link)
effect-native

CrSqlSchema overview

Schema definitions for CR-SQLite change tracking and serialization.

This module provides Effect Schema definitions for CR-SQLite data structures, including change rows, tracked peers, and various identifier types used throughout the CR-SQLite system.

Example

import * as CrSqlSchema from "@effect-native/crsql/CrSqlSchema"
import { Schema as S } from "effect"

// Validate a change row from CR-SQLite
const changeRow = {
  table: "users",
  pk: "1A2B3C4D",
  cid: "name",
  val: "Alice",
  val_type: "text",
  col_version: "1",
  db_version: "1",
  site_id: "A1B2C3D4E5F6789012345678ABCDEF90",
  cl: 0,
  seq: 0
}

const decoded = S.decodeUnknownSync(CrSqlSchema.ChangeRowSerialized)(changeRow)

Added in v0.1.0

Table of contents

Models

ChangeArray (type alias)

Signature

export type ChangeArray = typeof ChangeArray.Type

Added in v0.1.0

ChangeRowSerialized (type alias)

Signature

export type ChangeRowSerialized = typeof ChangeRowSerialized.Type

Added in v0.1.0

Changes (type alias)

Signature

export type Changes = typeof Changes.Type

Added in v0.1.0

ChangesArray (type alias)

Signature

export type ChangesArray = typeof ChangesArray.Type

Added in v0.1.0

ChangesObjects (type alias)

Signature

export type ChangesObjects = typeof ChangesObjects.Type

Added in v0.1.0

ExtInfo (type alias)

Signature

export type ExtInfo = typeof ExtInfo.Type

Added in v0.1.0

ExtInfoLoaded (type alias)

Signature

export type ExtInfoLoaded = typeof ExtInfoLoaded.Type

Added in v0.1.0

ExtInfoSql (type alias)

Signature

export type ExtInfoSql = typeof ExtInfoSql.Type

Added in v0.1.0

SiteIdHex (type alias)

Signature

export type SiteIdHex = typeof SiteIdHex.Type

Added in v0.1.0

SqlValueType (type alias)

Type alias for SQLite column value types.

Mirrors the encoded type of typeof(SqlValueType).Type.

Signature

export type SqlValueType = typeof SqlValueType.Type

Added in v0.1.0

TrackedPeerSerialized (type alias)

Signature

export type TrackedPeerSerialized = typeof TrackedPeerSerialized.Type

Added in v0.1.0

VersionString (type alias)

Signature

export type VersionString = typeof VersionString.Type

Added in v0.1.0

Schema

ChangeArray

Tuple (array) form of a serialized crsql_changes row.

Same fields and order as {@link ChangeRowSerialized}, but represented as a positional array instead of an object. Useful for compact transport formats or drivers that emit rows as arrays.

Field order: [table, pk, cid, val, val_type, col_version, db_version, site_id, cl, seq]

Signature

export declare const ChangeArray: S.Tuple<
  [
    S.filter<typeof S.String>,
    S.filter<typeof S.String>,
    S.filter<typeof S.String>,
    S.Union<[typeof S.Null, typeof S.String, typeof S.Number]>,
    S.Literal<["null", "text", "integer", "real", "blob"]>,
    S.refine<string, typeof S.String>,
    S.refine<string, typeof S.String>,
    S.filter<typeof S.String>,
    S.refine<number, typeof S.NonNegative>,
    S.refine<number, typeof S.NonNegative>
  ]
>

Added in v0.1.0

ChangeRowSerialized

Pre-serialized crsql_changes row for transport (IO boundary shape).

Represents a change row as returned by CR-SQLite with all fields serialized for transport across boundaries:

  • pk: hex string of BLOB primary key
  • val: null string number based on val_type:
    • if val_type === ‘blob’ then val is a hex string (SQL hex(val))
    • if val_type in (‘integer’, ‘real’) then val is a number
    • if val_type === ‘text’ then val is a string
  • col_version/db_version: bigint encoded as base-10 string (CAST AS TEXT in SQL)
  • site_id: hex string for site identity
  • cl/seq: non-negative integers

Signature

export declare const ChangeRowSerialized: S.Struct<{
  table: S.refine<string, typeof S.String>
  pk: S.refine<string, typeof S.String>
  cid: S.refine<string, typeof S.String>
  val: S.Union<[typeof S.Null, typeof S.String, typeof S.Number]>
  val_type: S.Literal<["null", "text", "integer", "real", "blob"]>
  col_version: S.refine<string, typeof S.String>
  db_version: S.refine<string, typeof S.String>
  site_id: S.refine<string, typeof S.String>
  cl: S.refine<number, typeof S.NonNegative>
  seq: S.refine<number, typeof S.NonNegative>
}>

Added in v0.1.0

Changes

Union schema accepting either array-of-objects or array-of-arrays encodings.

Signature

export declare const Changes: S.Union<
  [
    S.Array$<
      S.Struct<{
        table: S.refine<string, typeof S.String>
        pk: S.refine<string, typeof S.String>
        cid: S.refine<string, typeof S.String>
        val: S.Union<[typeof S.Null, typeof S.String, typeof S.Number]>
        val_type: S.Literal<["null", "text", "integer", "real", "blob"]>
        col_version: S.refine<string, typeof S.String>
        db_version: S.refine<string, typeof S.String>
        site_id: S.refine<string, typeof S.String>
        cl: S.refine<number, typeof S.NonNegative>
        seq: S.refine<number, typeof S.NonNegative>
      }>
    >,
    S.Array$<
      S.Tuple<
        [
          S.filter<typeof S.String>,
          S.filter<typeof S.String>,
          S.filter<typeof S.String>,
          S.Union<[typeof S.Null, typeof S.String, typeof S.Number]>,
          S.Literal<["null", "text", "integer", "real", "blob"]>,
          S.refine<string, typeof S.String>,
          S.refine<string, typeof S.String>,
          S.filter<typeof S.String>,
          S.refine<number, typeof S.NonNegative>,
          S.refine<number, typeof S.NonNegative>
        ]
      >
    >
  ]
>

Added in v0.1.0

ChangesArray

Signature

export declare const ChangesArray: S.Array$<
  S.Tuple<
    [
      S.filter<typeof S.String>,
      S.filter<typeof S.String>,
      S.filter<typeof S.String>,
      S.Union<[typeof S.Null, typeof S.String, typeof S.Number]>,
      S.Literal<["null", "text", "integer", "real", "blob"]>,
      S.refine<string, typeof S.String>,
      S.refine<string, typeof S.String>,
      S.filter<typeof S.String>,
      S.refine<number, typeof S.NonNegative>,
      S.refine<number, typeof S.NonNegative>
    ]
  >
>

Added in v0.1.0

ChangesObjects

Convenience schemas for batches of changes in both shapes.

These mirror the two common transport encodings:

  • Array of objects: ChangeRowSerialized[]
  • Array of arrays: ChangeArray[]

Signature

export declare const ChangesObjects: S.Array$<
  S.Struct<{
    table: S.refine<string, typeof S.String>
    pk: S.refine<string, typeof S.String>
    cid: S.refine<string, typeof S.String>
    val: S.Union<[typeof S.Null, typeof S.String, typeof S.Number]>
    val_type: S.Literal<["null", "text", "integer", "real", "blob"]>
    col_version: S.refine<string, typeof S.String>
    db_version: S.refine<string, typeof S.String>
    site_id: S.refine<string, typeof S.String>
    cl: S.refine<number, typeof S.NonNegative>
    seq: S.refine<number, typeof S.NonNegative>
  }>
>

Added in v0.1.0

ExtInfo

Complete information about a loaded CR-SQLite extension.

Contains both SQL-queryable information (SHA, site ID) and loading metadata (filesystem path, timestamp). Used when the extension has been successfully loaded and is ready for use.

Signature

export declare const ExtInfo: S.Struct<{
  sha: S.SchemaClass<string, string, never>
  siteId: S.filter<typeof S.String>
  path: S.NullOr<typeof S.String>
  loadedAt: S.transformOrFail<S.declare<Date, Date, readonly [], never>, typeof S.DateTimeUtcFromSelf, never>
}>

Added in v0.1.0

ExtInfoLoaded

Loading metadata for the CR-SQLite extension.

Contains information about when and from where the extension was loaded, but not the SQL-queryable information like SHA or site ID. Useful for debugging and auditing extension loading operations.

Signature

export declare const ExtInfoLoaded: S.Struct<{
  path: S.NullOr<typeof S.String>
  loadedAt: S.transformOrFail<S.declare<Date, Date, readonly [], never>, typeof S.DateTimeUtcFromSelf, never>
}>

Added in v0.1.0

ExtInfoSql

SQL-queryable information about the CR-SQLite extension.

Contains only the information that can be retrieved by querying the extension directly via SQL functions like crsql_sha() and crsql_site_id(). Does not include loading metadata like filesystem path or timestamp.

Signature

export declare const ExtInfoSql: S.Struct<{
  sha: S.SchemaClass<string, string, never>
  siteId: S.filter<typeof S.String>
}>

Added in v0.1.0

HexString

Basic hex string pattern (uppercase or lowercase) used for site_id and pk values.

Signature

export declare const HexString: S.filter<typeof S.String>

Added in v0.1.0

Identifier

Simple SQL identifier pattern.

Must start with letter or underscore, followed by letters, digits, or underscores.

Signature

export declare const Identifier: S.filter<typeof S.String>

Added in v0.1.0

SiteIdHex

Site ID as a 32-character hex string (16 bytes).

Signature

export declare const SiteIdHex: S.filter<typeof S.String>

Added in v0.1.0

SqlValueType

SQLite column value type from typeof() function.

Signature

export declare const SqlValueType: S.Literal<["null", "text", "integer", "real", "blob"]>

Added in v0.1.0

TrackedPeerSerialized

Pre-serialized crsql_tracked_peers row for transport (per-peer cursor).

Represents a tracked peer as returned by CR-SQLite with serialized fields:

  • site_id: hex string (16 bytes)
  • version: bigint encoded as base-10 string (CAST AS TEXT in SQL)
  • seq: non-negative integer

Signature

export declare const TrackedPeerSerialized: S.Struct<{
  site_id: S.filter<typeof S.String>
  version: S.refine<string, typeof S.String>
  seq: S.refine<number, typeof S.NonNegative>
}>

Added in v0.1.0

VersionString

Version string schema for CR-SQLite version fields.

Represents a bigint serialized as a base-10 string. There are two viable approaches for version fields in this codebase:

  1. Transport (string) only: keep versions as base-10 strings everywhere
    • Pro: avoids bigint parsing; matches SQL CAST(… AS TEXT) output
    • Con: consumers must parse to bigint for arithmetic/comparisons
  2. Parsed (bigint) in code + string at IO: use S.BigInt transformations
    • Pro: safe arithmetic in code; precise type
    • Con: requires transform step at IO boundaries

In “Serialized” schemas we use strings to faithfully represent boundary data.

Signature

export declare const VersionString: S.refine<string, typeof S.String>

Added in v0.1.0

isChangeArrayQuick

Fast guard that checks an unknown value is a tuple of length 10 in the order defined by {@link ChangeArray}. This does not validate element types.

Signature

export declare const isChangeArrayQuick: (it: unknown) => it is ChangeArray

Added in v0.1.0

isChangeRowSerializedQuick

Fast guard that checks an unknown value has the object shape of {@link ChangeRowSerialized} by verifying the presence of all expected keys. This does not perform deep type validation; use the schema for that.

Signature

export declare const isChangeRowSerializedQuick: (it: unknown) => it is ChangeRowSerialized

Added in v0.1.0

toChangeArray

Converts either an object-shaped change ({@link ChangeRowSerialized}) or a tuple-shaped change ({@link ChangeArray}) into the tuple form.

Signature

export declare const toChangeArray: (c: ChangeRowSerialized | ChangeArray) => ChangeArray

Added in v0.1.0