@electric-sql/client 0.3.1 → 0.3.3

package/src/client.ts

@@ -1,6 +1,6 @@
-import { ArgumentsType } from 'vitest'
 import { Message, Value, Offset, Schema } from './types'
 import { MessageParser, Parser } from './parser'
+import { isChangeMessage, isControlMessage } from './helpers'
 
 export type ShapeData = Map<string, { [key: string]: Value }>
 export type ShapeChangedCallback = (value: ShapeData) => void
@@ -196,7 +196,7 @@ export class ShapeStream {
     this.backoffOptions = options.backoffOptions ?? BackoffDefaults
     this.fetchClient =
       options.fetchClient ??
-      ((...args: ArgumentsType<typeof fetch>) => fetch(...args))
+      ((...args: Parameters<typeof fetch>) => fetch(...args))
 
     this.start()
   }
@@ -270,7 +270,8 @@ export class ShapeStream {
       if (batch.length > 0) {
         const lastMessage = batch[batch.length - 1]
         if (
-          lastMessage.headers?.[`control`] === `up-to-date` &&
+          isControlMessage(lastMessage) &&
+          lastMessage.headers.control === `up-to-date` &&
           !this.isUpToDate
         ) {
           this.isUpToDate = true
@@ -514,7 +515,7 @@ export class Shape {
     let newlyUpToDate = false
 
     messages.forEach((message) => {
-      if (`key` in message) {
+      if (isChangeMessage(message)) {
         dataMayHaveChanged = [`insert`, `update`, `delete`].includes(
           message.headers.operation
         )
@@ -535,19 +536,22 @@ export class Shape {
         }
       }
 
-      if (message.headers?.[`control`] === `up-to-date`) {
-        isUpToDate = true
-        if (!this.hasNotifiedSubscribersUpToDate) {
-          newlyUpToDate = true
+      if (isControlMessage(message)) {
+        switch (message.headers.control) {
+          case `up-to-date`:
+            isUpToDate = true
+            if (!this.hasNotifiedSubscribersUpToDate) {
+              newlyUpToDate = true
+            }
+            break
+          case `must-refetch`:
+            this.data.clear()
+            this.error = false
+            isUpToDate = false
+            newlyUpToDate = false
+            break
         }
       }
-
-      if (message.headers?.[`control`] === `must-refetch`) {
-        this.data.clear()
-        this.error = false
-        isUpToDate = false
-        newlyUpToDate = false
-      }
     })
 
     // Always notify subscribers when the Shape first is up to date.
@@ -561,6 +565,7 @@ export class Shape {
   private handleError(e: Error): void {
     if (e instanceof FetchError) {
       this.error = e
+      this.notify()
     }
   }
 

package/src/helpers.ts

@@ -0,0 +1,47 @@
+import { ChangeMessage, ControlMessage, Message, Value } from './types'
+
+/**
+ * Type guard for checking {@link Message} is {@link ChangeMessage}.
+ *
+ * See [TS docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards)
+ * for information on how to use type guards.
+ *
+ * @param message - the message to check
+ * @returns true if the message is a {@link ChangeMessage}
+ *
+ * @example
+ * ```ts
+ * if (isChangeMessage(message)) {
+ *   const msgChng: ChangeMessage = message // Ok
+ *   const msgCtrl: ControlMessage = message // Err, type mismatch
+ * }
+ * ```
+ */
+export function isChangeMessage<T extends Value = { [key: string]: Value }>(
+  message: Message<T>
+): message is ChangeMessage<T> {
+  return `key` in message
+}
+
+/**
+ * Type guard for checking {@link Message} is {@link ControlMessage}.
+ *
+ * See [TS docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards)
+ * for information on how to use type guards.
+ *
+ * @param message - the message to check
+ * @returns true if the message is a {@link ControlMessage}
+ *
+ *  * @example
+ * ```ts
+ * if (isControlMessage(message)) {
+ *   const msgChng: ChangeMessage = message // Err, type mismatch
+ *   const msgCtrl: ControlMessage = message // Ok
+ * }
+ * ```
+ */
+export function isControlMessage<T extends Value = { [key: string]: Value }>(
+  message: Message<T>
+): message is ControlMessage {
+  return !isChangeMessage(message)
+}

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './client'
 export * from './types'
+export * from './helpers'

package/src/parser.ts

@@ -1,7 +1,14 @@
 import { ColumnInfo, Message, Schema, Value } from './types'
 
+type NullToken = null | `NULL`
+type Token = Exclude<string, NullToken>
+type NullableToken = Token | NullToken
 export type ParseFunction = (
-  value: string,
+  value: Token,
+  additionalInfo?: Omit<ColumnInfo, `type` | `dims`>
+) => Value
+type NullableParseFunction = (
+  value: NullableToken,
   additionalInfo?: Omit<ColumnInfo, `type` | `dims`>
 ) => Value
 export type Parser = { [key: string]: ParseFunction }
@@ -10,6 +17,7 @@ const parseNumber = (value: string) => Number(value)
 const parseBool = (value: string) => value === `true` || value === `t`
 const parseBigInt = (value: string) => BigInt(value)
 const parseJson = (value: string) => JSON.parse(value)
+const identityParser: ParseFunction = (v: string) => v
 
 export const defaultParser: Parser = {
   int2: parseNumber,
@@ -23,10 +31,7 @@ export const defaultParser: Parser = {
 }
 
 // Taken from: https://github.com/electric-sql/pglite/blob/main/packages/pglite/src/types.ts#L233-L279
-export function pgArrayParser(
-  value: string,
-  parser?: (s: string) => Value
-): Value {
+export function pgArrayParser(value: Token, parser?: ParseFunction): Value {
   let i = 0
   let char = null
   let str = ``
@@ -92,7 +97,7 @@ export class MessageParser {
         // Parse the row values
         const row = value as Record<string, Value>
         Object.keys(row).forEach((key) => {
-          row[key] = this.parseRow(key, row[key] as string, schema)
+          row[key] = this.parseRow(key, row[key] as NullableToken, schema)
         })
       }
       return value
@@ -100,7 +105,7 @@ export class MessageParser {
   }
 
   // Parses the message values using the provided parser based on the schema information
-  private parseRow(key: string, value: string, schema: Schema): Value {
+  private parseRow(key: string, value: NullableToken, schema: Schema): Value {
     const columnInfo = schema[key]
     if (!columnInfo) {
       // We don't have information about the value
@@ -114,13 +119,17 @@ export class MessageParser {
     // Pick the right parser for the type
     // and support parsing null values if needed
     // if no parser is provided for the given type, just return the value as is
-    const identityParser = (v: string) => v
-    const typParser = this.parser[typ] ?? identityParser
-    const parser = makeNullableParser(typParser, columnInfo.not_null)
+    const typeParser = this.parser[typ] ?? identityParser
+    const parser = makeNullableParser(typeParser, columnInfo, key)
 
     if (dimensions && dimensions > 0) {
       // It's an array
-      return pgArrayParser(value, parser)
+      const nullablePgArrayParser = makeNullableParser(
+        (value, _) => pgArrayParser(value, parser),
+        columnInfo,
+        key
+      )
+      return nullablePgArrayParser(value)
     }
 
     return parser(value, additionalInfo)
@@ -129,15 +138,24 @@ export class MessageParser {
 
 function makeNullableParser(
   parser: ParseFunction,
-  notNullable?: boolean
-): ParseFunction {
-  const isNullable = !(notNullable ?? false)
-  if (isNullable) {
-    // The sync service contains `null` value for a column whose value is NULL
-    // but if the column value is an array that contains a NULL value
-    // then it will be included in the array string as `NULL`, e.g.: `"{1,NULL,3}"`
-    return (value: string) =>
-      value === null || value === `NULL` ? null : parser(value)
+  columnInfo: ColumnInfo,
+  columnName?: string
+): NullableParseFunction {
+  const isNullable = !(columnInfo.not_null ?? false)
+  // The sync service contains `null` value for a column whose value is NULL
+  // but if the column value is an array that contains a NULL value
+  // then it will be included in the array string as `NULL`, e.g.: `"{1,NULL,3}"`
+  return (value: NullableToken) => {
+    if (isPgNull(value)) {
+      if (!isNullable) {
+        throw new Error(`Column ${columnName ?? `unknown`} is not nullable`)
+      }
+      return null
+    }
+    return parser(value, columnInfo)
   }
-  return parser
+}
+
+function isPgNull(value: NullableToken): value is NullToken {
+  return value === null || value === `NULL`
 }

package/src/types.ts

@@ -10,11 +10,11 @@ export type Value =
 export type Offset = `-1` | `${number}_${number}`
 
 interface Header {
-  [key: string]: Value
+  [key: Exclude<string, `operation` | `control`>]: Value
 }
 
 export type ControlMessage = {
-  headers: Header
+  headers: Header & { control: `up-to-date` | `must-refetch` }
 }
 
 export type ChangeMessage<T> = {