@syncular/core 0.1.3 → 0.2.1

package/src/blobs.ts

@@ -1,219 +0,0 @@
-/**
- * @syncular/core - Blob types for media/binary handling
- *
- * Content-addressable blob storage with presigned URL support.
- * Protocol types (BlobRef, BlobMetadata, etc.) live in ./schemas/blobs.ts
- */
-
-import type { BlobRef } from './schemas/blobs';
-
-// ============================================================================
-// Client Transport Types
-// ============================================================================
-
-/**
- * Transport interface for client-server blob communication.
- * This is used by the client blob manager to communicate with the server.
- */
-export interface BlobTransport {
-  /**
-   * Initiate a blob upload.
-   * Returns presigned URL info or indicates blob already exists (dedup).
-   */
-  initiateUpload(args: {
-    hash: string;
-    size: number;
-    mimeType: string;
-  }): Promise<{
-    exists: boolean;
-    uploadUrl?: string;
-    uploadMethod?: 'PUT' | 'POST';
-    uploadHeaders?: Record<string, string>;
-  }>;
-
-  /**
-   * Complete a blob upload.
-   * Call this after uploading to the presigned URL.
-   */
-  completeUpload(hash: string): Promise<{ ok: boolean; error?: string }>;
-
-  /**
-   * Get a presigned download URL.
-   */
-  getDownloadUrl(hash: string): Promise<{
-    url: string;
-    expiresAt: string;
-  }>;
-}
-
-// ============================================================================
-// Storage Adapter Types (Server-side)
-// ============================================================================
-
-/**
- * Options for signing an upload URL.
- */
-export interface BlobSignUploadOptions {
-  /** SHA-256 hash (for naming and checksum validation) */
-  hash: string;
-  /** Optional tenant/partition namespace for storage lookups */
-  partitionId?: string;
-  /** Content size in bytes */
-  size: number;
-  /** MIME type */
-  mimeType: string;
-  /** URL expiration in seconds */
-  expiresIn: number;
-}
-
-/**
- * Result of signing an upload URL.
- */
-export interface BlobSignedUpload {
-  /** The URL to upload to */
-  url: string;
-  /** HTTP method */
-  method: 'PUT' | 'POST';
-  /** Required headers */
-  headers?: Record<string, string>;
-}
-
-/**
- * Options for signing a download URL.
- */
-export interface BlobSignDownloadOptions {
-  /** SHA-256 hash */
-  hash: string;
-  /** Optional tenant/partition namespace for storage lookups */
-  partitionId?: string;
-  /** URL expiration in seconds */
-  expiresIn: number;
-}
-
-export interface BlobStoragePartitionOptions {
-  partitionId?: string;
-}
-
-/**
- * Adapter for blob storage backends (S3, R2, custom).
- * Implementations handle actual storage; the sync server orchestrates.
- */
-export interface BlobStorageAdapter {
-  /** Adapter name for logging/debugging */
-  readonly name: string;
-
-  /**
-   * Generate a presigned URL for uploading a blob.
-   * The URL should enforce checksum validation if the backend supports it.
-   */
-  signUpload(options: BlobSignUploadOptions): Promise<BlobSignedUpload>;
-
-  /**
-   * Generate a presigned URL for downloading a blob.
-   */
-  signDownload(options: BlobSignDownloadOptions): Promise<string>;
-
-  /**
-   * Check if a blob exists in storage.
-   */
-  exists(hash: string, options?: BlobStoragePartitionOptions): Promise<boolean>;
-
-  /**
-   * Delete a blob (for garbage collection).
-   */
-  delete(hash: string, options?: BlobStoragePartitionOptions): Promise<void>;
-
-  /**
-   * Get blob metadata from storage (optional).
-   * Used to verify uploads completed successfully.
-   */
-  getMetadata?(
-    hash: string,
-    options?: BlobStoragePartitionOptions
-  ): Promise<{ size: number; mimeType?: string } | null>;
-
-  /**
-   * Store blob data directly (for adapters that support direct storage).
-   * Used for snapshot chunks and other internal data.
-   */
-  put?(
-    hash: string,
-    data: Uint8Array,
-    metadata?: Record<string, unknown>,
-    options?: BlobStoragePartitionOptions
-  ): Promise<void>;
-
-  /**
-   * Store blob data directly from a stream.
-   * Preferred for large payloads to avoid full buffering in memory.
-   */
-  putStream?(
-    hash: string,
-    stream: ReadableStream<Uint8Array>,
-    metadata?: Record<string, unknown>,
-    options?: BlobStoragePartitionOptions
-  ): Promise<void>;
-
-  /**
-   * Get blob data directly (for adapters that support direct retrieval).
-   */
-  get?(
-    hash: string,
-    options?: BlobStoragePartitionOptions
-  ): Promise<Uint8Array | null>;
-
-  /**
-   * Get blob data directly as a stream (for adapters that support stream retrieval).
-   */
-  getStream?(
-    hash: string,
-    options?: BlobStoragePartitionOptions
-  ): Promise<ReadableStream<Uint8Array> | null>;
-}
-
-// ============================================================================
-// Utility Functions
-// ============================================================================
-
-/**
- * Create a BlobRef from upload metadata.
- */
-export function createBlobRef(args: {
-  hash: string;
-  size: number;
-  mimeType: string;
-  encrypted?: boolean;
-  keyId?: string;
-}): BlobRef {
-  const ref: BlobRef = {
-    hash: args.hash,
-    size: args.size,
-    mimeType: args.mimeType,
-  };
-  if (args.encrypted) {
-    ref.encrypted = true;
-    if (args.keyId) {
-      ref.keyId = args.keyId;
-    }
-  }
-  return ref;
-}
-
-/**
- * Parse a blob hash, validating format.
- * @returns The hex hash without prefix, or null if invalid.
- */
-export function parseBlobHash(hash: string): string | null {
-  if (!hash.startsWith('sha256:')) return null;
-  const hex = hash.slice(7);
-  if (hex.length !== 64) return null;
-  if (!/^[0-9a-f]+$/i.test(hex)) return null;
-  return hex.toLowerCase();
-}
-
-/**
- * Create a blob hash string from hex.
- */
-export function createBlobHash(hexHash: string): string {
-  return `sha256:${hexHash.toLowerCase()}`;
-}

package/src/column-codecs.ts

@@ -1,262 +0,0 @@
-import type { SqlFamily } from './dialect';
-
-export type ColumnCodecDialect = SqlFamily;
-
-export interface ColumnCodecTypeImport {
-  name: string;
-  from: string;
-}
-
-export type ColumnCodecType =
-  | string
-  | { type: string; import?: ColumnCodecTypeImport };
-
-export interface ColumnCodec<App, Db> {
-  ts: ColumnCodecType;
-  toDb(value: App): Db;
-  fromDb(value: Db): App;
-  dialects?: Partial<
-    Record<
-      ColumnCodecDialect,
-      {
-        toDb?(value: App): Db;
-        fromDb?(value: Db): App;
-      }
-    >
-  >;
-}
-
-export type AnyColumnCodec = ColumnCodec<unknown, unknown>;
-
-export interface ColumnCodecColumn {
-  table: string;
-  column: string;
-  sqlType?: string;
-  nullable?: boolean;
-  isPrimaryKey?: boolean;
-  hasDefault?: boolean;
-  dialect?: ColumnCodecDialect;
-}
-
-export type TableColumnCodecs = Record<string, AnyColumnCodec>;
-
-export type ColumnCodecSource = (
-  column: ColumnCodecColumn
-) => AnyColumnCodec | undefined;
-
-function hasCodecs(tableCodecs: TableColumnCodecs): boolean {
-  return Object.keys(tableCodecs).length > 0;
-}
-
-function resolveCodecToDb(
-  codec: AnyColumnCodec,
-  dialect: ColumnCodecDialect
-): (value: unknown) => unknown {
-  return codec.dialects?.[dialect]?.toDb ?? codec.toDb;
-}
-
-function resolveCodecFromDb(
-  codec: AnyColumnCodec,
-  dialect: ColumnCodecDialect
-): (value: unknown) => unknown {
-  return codec.dialects?.[dialect]?.fromDb ?? codec.fromDb;
-}
-
-export function toTableColumnCodecs(
-  table: string,
-  codecSource: ColumnCodecSource | undefined,
-  columns: Iterable<string>,
-  options: {
-    dialect?: ColumnCodecDialect;
-    sqlTypes?: Record<string, string | undefined>;
-  } = {}
-): TableColumnCodecs {
-  if (!codecSource) return {};
-  const out: TableColumnCodecs = {};
-
-  for (const column of columns) {
-    if (column.length === 0) continue;
-    const codec = codecSource({
-      table,
-      column,
-      sqlType: options.sqlTypes?.[column],
-      dialect: options.dialect,
-    });
-    if (codec) out[column] = codec;
-  }
-
-  return out;
-}
-
-export function createTableColumnCodecsResolver(
-  codecSource: ColumnCodecSource | undefined,
-  options: { dialect?: ColumnCodecDialect } = {}
-): (table: string, row: Record<string, unknown>) => TableColumnCodecs {
-  const tableCaches = new Map<string, Map<string, TableColumnCodecs>>();
-
-  return (table, row) => {
-    if (!codecSource) return {};
-    const columns = Object.keys(row);
-    if (columns.length === 0) return {};
-
-    const cacheKey = columns.slice().sort().join('\u0000');
-    let perTableCache = tableCaches.get(table);
-    if (!perTableCache) {
-      perTableCache = new Map<string, TableColumnCodecs>();
-      tableCaches.set(table, perTableCache);
-    }
-
-    const cached = perTableCache.get(cacheKey);
-    if (cached) return cached;
-
-    const resolved = toTableColumnCodecs(table, codecSource, columns, {
-      dialect: options.dialect,
-    });
-    perTableCache.set(cacheKey, resolved);
-    return resolved;
-  };
-}
-
-export function applyCodecToDbValue(
-  codec: AnyColumnCodec,
-  value: unknown,
-  dialect: ColumnCodecDialect = 'sqlite'
-): unknown {
-  if (value === null || value === undefined) return value;
-  const transform = resolveCodecToDb(codec, dialect);
-  return transform(value);
-}
-
-export function applyCodecFromDbValue(
-  codec: AnyColumnCodec,
-  value: unknown,
-  dialect: ColumnCodecDialect = 'sqlite'
-): unknown {
-  if (value === null || value === undefined) return value;
-  const transform = resolveCodecFromDb(codec, dialect);
-  return transform(value);
-}
-
-export function applyCodecsToDbRow(
-  row: Record<string, unknown>,
-  tableCodecs: TableColumnCodecs,
-  dialect: ColumnCodecDialect = 'sqlite'
-): Record<string, unknown> {
-  if (!hasCodecs(tableCodecs)) return { ...row };
-
-  const transformed: Record<string, unknown> = { ...row };
-  for (const [column, codec] of Object.entries(tableCodecs)) {
-    if (!(column in transformed)) continue;
-    transformed[column] = applyCodecToDbValue(
-      codec,
-      transformed[column],
-      dialect
-    );
-  }
-  return transformed;
-}
-
-export function applyCodecsFromDbRow(
-  row: Record<string, unknown>,
-  tableCodecs: TableColumnCodecs,
-  dialect: ColumnCodecDialect = 'sqlite'
-): Record<string, unknown> {
-  if (!hasCodecs(tableCodecs)) return { ...row };
-
-  let transformed: Record<string, unknown> | null = null;
-  for (const [column, codec] of Object.entries(tableCodecs)) {
-    if (!(column in row)) continue;
-    const value = row[column];
-    if (value === null || value === undefined) continue;
-    transformed ??= { ...row };
-    transformed[column] = applyCodecFromDbValue(codec, value, dialect);
-  }
-  return transformed ?? row;
-}
-
-function parseBooleanValue(value: unknown): boolean {
-  if (typeof value === 'boolean') return value;
-  if (typeof value === 'number') return value !== 0;
-  if (typeof value === 'string') {
-    const normalized = value.trim().toLowerCase();
-    if (normalized === 'true' || normalized === 't') return true;
-    if (normalized === 'false' || normalized === 'f') return false;
-    const asNumber = Number(normalized);
-    if (Number.isFinite(asNumber)) return asNumber !== 0;
-    return false;
-  }
-  return Boolean(value);
-}
-
-export function numberBoolean(): ColumnCodec<
-  boolean,
-  number | boolean | string
-> {
-  return {
-    ts: 'boolean',
-    toDb: (value) => (value ? 1 : 0),
-    fromDb: (value) => parseBooleanValue(value),
-    dialects: {
-      postgres: {
-        toDb: (value) => value,
-        fromDb: (value) => parseBooleanValue(value),
-      },
-    },
-  };
-}
-
-export interface StringJsonCodecOptions<T> {
-  ts?: ColumnCodecType;
-  import?: ColumnCodecTypeImport;
-  stringify?: (value: T) => string;
-  parse?: (value: string) => T;
-}
-
-export function stringJson<T = unknown>(
-  options: StringJsonCodecOptions<T> = {}
-): ColumnCodec<T, string | T> {
-  const stringify = options.stringify ?? ((value: T) => JSON.stringify(value));
-  const parse = options.parse ?? ((value: string) => JSON.parse(value) as T);
-
-  const ts: ColumnCodecType =
-    options.ts ??
-    (options.import
-      ? { type: options.import.name, import: options.import }
-      : 'unknown');
-
-  return {
-    ts,
-    toDb: (value) => stringify(value),
-    fromDb: (value) => {
-      if (typeof value === 'string') {
-        return parse(value);
-      }
-      return value as T;
-    },
-  };
-}
-
-export function timestampDate(): ColumnCodec<Date, string | Date> {
-  return {
-    ts: 'Date',
-    toDb: (value) => value.toISOString(),
-    fromDb: (value) =>
-      value instanceof Date ? value : new Date(String(value)),
-  };
-}
-
-export function dateString(): ColumnCodec<string, string | Date> {
-  return {
-    ts: 'string',
-    toDb: (value) => value,
-    fromDb: (value) =>
-      value instanceof Date ? value.toISOString().slice(0, 10) : String(value),
-  };
-}
-
-export const codecs = {
-  numberBoolean,
-  stringJson,
-  timestampDate,
-  dateString,
-};

package/src/conflict.ts

@@ -1,92 +0,0 @@
-/**
- * @syncular/core - Pure conflict detection and field-level merge utilities
- *
- * These are pure functions with no database dependencies.
- * Database-specific conflict detection (triggers, etc.) lives in @syncular/server.
- */
-
-import type { MergeResult } from './types';
-
-/**
- * Performs field-level merge between client changes and server state.
- *
- * Merge logic:
- * - If only client changed a field -> use client's value
- * - If only server changed a field -> keep server's value
- * - If both changed same field to different values -> true conflict
- *
- * @param baseRow - The row state when client started editing (from base_version)
- * @param serverRow - Current server row state
- * @param clientPayload - Client's intended changes
- * @returns MergeResult indicating if merge is possible and the result
- */
-export function performFieldLevelMerge(
-  baseRow: Record<string, unknown> | null,
-  serverRow: Record<string, unknown>,
-  clientPayload: Record<string, unknown>
-): MergeResult {
-  // If no base row (new insert), client payload wins entirely
-  if (!baseRow) {
-    return { canMerge: true, mergedPayload: clientPayload };
-  }
-
-  const conflictingFields: string[] = [];
-  const mergedPayload: Record<string, unknown> = { ...serverRow };
-
-  // Check each field in the client payload
-  for (const [field, clientValue] of Object.entries(clientPayload)) {
-    const baseValue = baseRow[field];
-    const serverValue = serverRow[field];
-
-    const clientChanged = !deepEqual(baseValue, clientValue);
-    const serverChanged = !deepEqual(baseValue, serverValue);
-
-    if (clientChanged && serverChanged) {
-      // Both changed the same field
-      if (!deepEqual(clientValue, serverValue)) {
-        // Changed to different values - true conflict
-        conflictingFields.push(field);
-      }
-      // If they changed to the same value, no conflict - use either
-      mergedPayload[field] = clientValue;
-    } else if (clientChanged) {
-      // Only client changed - use client's value
-      mergedPayload[field] = clientValue;
-    }
-    // If only server changed or neither changed, keep server value (already in mergedPayload)
-  }
-
-  if (conflictingFields.length > 0) {
-    return { canMerge: false, conflictingFields };
-  }
-
-  return { canMerge: true, mergedPayload };
-}
-
-/**
- * Deep equality check for values (handles primitives, arrays, objects)
- */
-function deepEqual(a: unknown, b: unknown): boolean {
-  if (a === b) return true;
-  if (a === null || b === null) return a === b;
-  if (typeof a !== typeof b) return false;
-
-  if (typeof a === 'object') {
-    if (Array.isArray(a) && Array.isArray(b)) {
-      if (a.length !== b.length) return false;
-      return a.every((item, index) => deepEqual(item, b[index]));
-    }
-
-    if (Array.isArray(a) || Array.isArray(b)) return false;
-
-    const aObj = a as Record<string, unknown>;
-    const bObj = b as Record<string, unknown>;
-    const aKeys = Object.keys(aObj);
-    const bKeys = Object.keys(bObj);
-
-    if (aKeys.length !== bKeys.length) return false;
-    return aKeys.every((key) => deepEqual(aObj[key], bObj[key]));
-  }
-
-  return false;
-}

package/src/database.ts

@@ -1,21 +0,0 @@
-import { Kysely } from 'kysely';
-import type { ColumnCodecSource } from './column-codecs';
-import type { SqlFamily, SyncularDialectDescriptor } from './dialect';
-import { createColumnCodecsPlugin } from './kysely-column-codecs';
-
-export function createDatabase<T, F extends SqlFamily = SqlFamily>(
-  options: SyncularDialectDescriptor<F> & {
-    codecs?: ColumnCodecSource;
-  }
-) {
-  const db = new Kysely<T>({
-    dialect: options.dialect,
-  });
-  if (!options.codecs) return db;
-  return db.withPlugin(
-    createColumnCodecsPlugin({
-      codecs: options.codecs,
-      dialect: options.family,
-    })
-  );
-}

package/src/dialect.ts

@@ -1,8 +0,0 @@
-import type { Dialect } from 'kysely';
-
-export type SqlFamily = 'sqlite' | 'postgres';
-
-export interface SyncularDialectDescriptor<F extends SqlFamily = SqlFamily> {
-  dialect: Dialect;
-  family: F;
-}