@juit/pgproxy-types 1.0.0

package/src/serializers/date.ts

@@ -0,0 +1,63 @@
+/** Pad a number with zeroes to the specified number of digits */
+function pad(number: number, digits: number): string {
+  return number.toString().padStart(digits, '0')
+}
+
+// /* THIS IS UNTESTABLE: We can't set the timezone offset in a JavaScript date,
+//  * it's always the _local_ one (which basically means, depends on where the
+//  * tester actually _is_)... So until we get some inspiration, let's keep the
+//  * code here but don't develop it further... */
+//
+// /** Serialize a {@link Date} as a timestamp preserving its time zone */
+// export function serializeDateWithTimezone(date: Date): string {
+//   if (isNaN(date.getTime())) throw new TypeError('Attempted to serialize invalid date')
+//
+//   let offset = -date.getTimezoneOffset()
+//
+//   let year = date.getFullYear()
+//   const isBCYear = year < 1
+//   if (isBCYear) year = Math.abs(year) + 1 // negative years are 1 off their BC representation
+//
+//   let result =
+//     pad(year, 4) + '-' +
+//     pad(date.getMonth() + 1, 2) + '-' +
+//     pad(date.getDate(), 2) + 'T' +
+//     pad(date.getHours(), 2) + ':' +
+//     pad(date.getMinutes(), 2) + ':' +
+//     pad(date.getSeconds(), 2) + '.' +
+//     pad(date.getMilliseconds(), 3)
+//
+//   if (offset < 0) {
+//     result += '-'
+//     offset *= -1
+//   } else {
+//     result += '+'
+//   }
+//
+//   result += pad(Math.floor(offset / 60), 2) + ':' + pad(offset % 60, 2)
+//   if (isBCYear) result += ' BC'
+//
+//   return result
+// }
+
+/** Serialize a {@link Date} as a timestamp always in the UTC time zone */
+export function serializeDateUTC(date: Date): string {
+  if (isNaN(date.getTime())) throw new TypeError('Attempted to serialize invalid date')
+
+  let year = date.getUTCFullYear()
+  const isBCYear = year < 1
+  if (isBCYear) year = Math.abs(year) + 1 // negative years are 1 off their BC representation
+
+  let ret =
+    pad(year, 4) + '-' +
+    pad(date.getUTCMonth() + 1, 2) + '-' +
+    pad(date.getUTCDate(), 2) + 'T' +
+    pad(date.getUTCHours(), 2) + ':' +
+    pad(date.getUTCMinutes(), 2) + ':' +
+    pad(date.getUTCSeconds(), 2) + '.' +
+    pad(date.getUTCMilliseconds(), 3)
+
+  ret += '+00:00'
+  if (isBCYear) ret += ' BC'
+  return ret
+}

package/src/serializers.ts

@@ -0,0 +1,165 @@
+import { serializeByteA } from './serializers/bytea'
+import { serializeDateUTC } from './serializers/date'
+
+/** A cache storing serialized versions of objects */
+const serializationCache = new WeakMap<object, string>()
+
+/** Quote (escape with "quotes") a string */
+function quote(string: string): string {
+  return `"${string.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+}
+
+/** Serialize an {@link Array} as a PosgreSQL `ARRAY` */
+function serializeArray(value: any[], stack: WeakSet<object>): string {
+  const result = new Array<string>(value.length)
+
+  for (let i = 0; i < value.length; i ++) {
+    const member = value[i]
+    const type = typeof member
+
+    /* Nulls (or undefined, we consider them same) are the unquoted "NULL" */
+    if ((member === null) || (member === undefined)) {
+      result[i] = 'NULL'
+
+    /* Booleans are simply "t" or "f" */
+    } else if (type === 'boolean') {
+      result[i] = member ? 't' : 'f'
+
+    /* Numbers and booleans can be left unquoted */
+    } else if ((type === 'bigint') || (type === 'number')) {
+      result[i] = `${member}`
+
+    /* Arrays are a beast on their own: we leave them unquoted, and we can
+     * short-circuit on "serializeArray" directly, but in this case we have
+     * to manually manage our cache and our stack... */
+    } else if (Array.isArray(member)) {
+      const cached = serializationCache.get(member)
+      if (cached) {
+        result[i] = cached
+      } else {
+        if (stack.has(member)) throw new TypeError('Circularity detected serializing')
+        stack.add(member) // we bypass "valueSerializer", so add to the stack
+        result[i] = serializeArray(member, stack) // invoke ourselves
+        serializationCache.set(member, result[i]!) // cache the result
+        stack.delete(member) // then remove the member from the stack
+      }
+
+    /* BYTEA representations must be quoted as well in arrays, but as we know
+     * their representation is always '\x0123456789abcdef', we can avoid the
+     * expensive regex in 'quote' and wrap the result manually */
+    } else if (ArrayBuffer.isView(member)) {
+      result[i] = `"\\${serializeByteA(member)}"`
+
+    /* Everything else gets serialized *and* properly quoted */
+    } else {
+      result[i] = quote(serializeValue(member, stack))
+    }
+  }
+
+  return `{${result.join(',')}}`
+}
+
+/** Serialize any value into its PostgreSQL string equivalent */
+function serializeValue(value: any, stack: WeakSet<object>): string {
+  /* Never "null" */
+  if (value === null) throw new TypeError('Can not serialize "null"')
+
+  /* Basic primitives */
+  switch (typeof value) {
+    case 'string':
+      return value
+
+    case 'boolean':
+      return value ? 't' : 'f'
+
+    case 'bigint':
+    case 'number':
+      return value.toString()
+
+    case 'object':
+      break
+
+    case 'function':
+    case 'symbol':
+    case 'undefined':
+    default:
+      throw new TypeError(`Can not serialize "${typeof value}"`)
+  }
+
+  /* All primitives, "null" or "undefined" are resolved, value is "object" */
+
+  /* Check caches */
+  const cached = serializationCache.get(value)
+  if (cached !== undefined) return cached
+
+  /* Check for loops */
+  if (stack.has(value)) throw new TypeError('Circularity detected serializing')
+  stack.add(value)
+
+  /* Create a sub-serializer to serialize values (it carries our stack) */
+  const subserialize = ((v: any) => serializeValue(v, stack)) as PGSerialize
+
+  /* The string we serialized */
+  let string: string
+
+  /* PGSerializable objects */
+  if (isPGSerializable(value)) {
+    string = value.toPostgres(subserialize)
+
+  /* Buffers, Uint8Arrays, and all other ArrayBufferViews */
+  } else if (ArrayBuffer.isView(value)) {
+    string = serializeByteA(value)
+
+  /* Arrays */
+  } else if (Array.isArray(value)) {
+    string = serializeArray(value, stack)
+
+  /* Dates: for now always UTC, but we have the code for including TZ */
+  } else if (value instanceof Date) {
+    string = serializeDateUTC(value)
+
+  /* Any other object gets serialized as JSON */
+  } else {
+    string = JSON.stringify(value)
+  }
+
+  /* Cache the resulting string, pop value out of the stack and return */
+  serializationCache.set(value, string)
+  stack.delete(value)
+  return string
+}
+
+/** Type guard identifying {@link PGSerializable} instances */
+function isPGSerializable(value: any): value is PGSerializable {
+  return value && (typeof value['toPostgres'] === 'function')
+}
+
+/* ========================================================================== *
+ * EXPORTED SERIALIZATION INTERFACE                                           *
+ * ========================================================================== */
+
+/**
+ * Defines an object that can be serialized to a _string_ comprehensible by
+ * PostgreSQL.
+ *
+ * The `serialize` parameter is a serialization function which can be used
+ * to serialize _members_ of the {@link PGSerializable} itself (e.g. boundaries
+ * of a {@link PGRange}, members of an _array_, ...).
+ */
+export interface PGSerializable {
+  toPostgres(serialize: PGSerialize): string
+}
+
+/** An interface describing our {@link serialize} function. */
+export interface PGSerialize {
+  (value?: null | undefined): never
+  (value: any): string
+}
+
+/** Serialize a value to _string_ comprehensible by PostgreSQL. */
+export const serialize: PGSerialize =
+  ((value: any) => serializeValue(value, new WeakSet())) as PGSerialize
+
+/* All other exported serializers */
+export { serializeByteA } from './serializers/bytea'
+export { serializeDateUTC } from './serializers/date'