@trainstar/synchro-react-native 0.3.1 → 0.4.0-rc.1

package/src/SynchroClient.ts

@@ -28,6 +28,8 @@ import type {
   MutationRejectionCode,
   PendingMutationInspection,
   RejectedMutationInspection,
+  RetainedMutationInspection,
+  RetainedRejectionInspection,
   ClientStateInspection,
   ScopeStateInspection,
   ScopeRowInspection,
@@ -117,6 +119,7 @@ const MUTATION_REJECTION_CODES: readonly MutationRejectionCode[] = [
   'policy_rejected',
   'validation_failed',
   'table_not_synced',
+  'atomic_batch_rejected',
 ];
 
 const MUTATION_OPERATIONS = ['insert', 'upsert', 'update', 'delete'] as const;
@@ -127,6 +130,7 @@ const LOCAL_MUTATION_STATUSES = [
   'cancelled_before_send',
   'blocked_by_predecessor',
   'server_rejected',
+  'exceeds_push_limit',
 ] as const;
 
 const TRANSPORT_OPERATION_CLASSES: readonly TransportOperationClass[] = [
@@ -437,6 +441,40 @@ function parsePendingMutationInspection(
   };
 }
 
+export function parseRetainedMutationInspection(
+  value: unknown,
+  index: number
+): RetainedMutationInspection {
+  const name = `pending mutation at index ${index}`;
+  if (!isRecord(value)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  if (value.representation === 'current') {
+    return { representation: 'current', ...parsePendingMutationInspection(value, index) };
+  }
+  if (value.representation !== 'legacy') {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name} representation`);
+  }
+  if (!MUTATION_OPERATIONS.includes(value.operation as never)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name} operation`);
+  }
+  if (!LOCAL_MUTATION_STATUSES.includes(value.status as never)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name} status`);
+  }
+  return {
+    representation: 'legacy',
+    mutationID: requiredString(value.mutationID, `${name} ID`),
+    localOrder: requiredSafeInteger(value.localOrder, `${name} local order`),
+    tableName: requiredString(value.tableName, `${name} table name`),
+    recordID: requiredString(value.recordID, `${name} record ID`),
+    operation: value.operation as PendingMutationInspection['operation'],
+    baseVersion: nullableString(value.baseVersion, `${name} base version`),
+    clientVersion: requiredString(value.clientVersion, `${name} client version`),
+    status: value.status as PendingMutationInspection['status'],
+    sourceKind: requiredString(value.sourceKind, `${name} source kind`),
+  };
+}
+
 function parseRejectedMutationInspection(
   value: unknown,
   index: number
@@ -465,6 +503,39 @@ function parseRejectedMutationInspection(
   };
 }
 
+export function parseRetainedRejectionInspection(
+  value: unknown,
+  index: number
+): RetainedRejectionInspection {
+  const name = `rejected mutation at index ${index}`;
+  if (!isRecord(value)) {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name}`);
+  }
+  if (value.representation === 'current') {
+    return { representation: 'current', ...parseRejectedMutationInspection(value, index) };
+  }
+  if (value.representation !== 'legacy') {
+    throw new InvalidResponseError(`Native bridge returned an invalid ${name} representation`);
+  }
+  const code = parseRejectionCode(value.code);
+  if (code === null) {
+    throw new InvalidResponseError(`Native bridge returned a missing ${name} code`);
+  }
+  return {
+    representation: 'legacy',
+    mutationID: requiredString(value.mutationID, `${name} ID`),
+    tableName: requiredString(value.tableName, `${name} table name`),
+    recordID: requiredString(value.recordID, `${name} record ID`),
+    status: parseMutationStatus(value.status),
+    code,
+    message: nullableString(value.message, `${name} message`),
+    serverRowJSON: nullableString(value.serverRowJSON, `${name} server row JSON`),
+    serverVersion: nullableString(value.serverVersion, `${name} server version`),
+    createdAt: requiredString(value.createdAt, `${name} creation time`),
+    updatedAt: requiredString(value.updatedAt, `${name} update time`),
+  };
+}
+
 function parseScopeStateInspection(value: unknown, index: number): ScopeStateInspection {
   const name = `scope state at index ${index}`;
   if (!isRecord(value)) {
@@ -801,10 +872,28 @@ export class SynchroClient {
 
   async writeTransaction<T>(
     callback: (tx: Transaction) => Promise<T>
+  ): Promise<T> {
+    return this.runWriteTransaction(() => this.native.beginWriteTransaction(), callback);
+  }
+
+  /**
+   * Runs a write transaction whose synced mutations the server applies all
+   * together or not at all. The native SDK owns the group. An invalid group
+   * rolls back and rejects with `AtomicGroupInvalidError`.
+   */
+  async atomicWriteTransaction<T>(
+    callback: (tx: Transaction) => Promise<T>
+  ): Promise<T> {
+    return this.runWriteTransaction(() => this.native.beginAtomicWriteTransaction(), callback);
+  }
+
+  private async runWriteTransaction<T>(
+    begin: () => Promise<string>,
+    callback: (tx: Transaction) => Promise<T>
   ): Promise<T> {
     let txID: string;
     try {
-      txID = await this.native.beginWriteTransaction();
+      txID = await begin();
     } catch (error) {
       throw mapNativeError(error);
     }
@@ -1024,6 +1113,11 @@ export class SynchroClient {
     }
   }
 
+  /**
+   * Returns the unresolved queue records.
+   * @deprecated Use {@link SynchroClient.inspectRetainedMutationRecords}. This method keeps its
+   * published behavior. It rejects when the native queue holds a legacy import.
+   */
   async inspectPendingMutations(): Promise<PendingMutationInspection[]> {
     try {
       return parseNativeArray(
@@ -1035,6 +1129,11 @@ export class SynchroClient {
     }
   }
 
+  /**
+   * Returns every retained queue record, including local terminal states.
+   * @deprecated Use {@link SynchroClient.inspectRetainedMutationRecords}. This method keeps its
+   * published behavior. It rejects when the native queue holds a legacy import.
+   */
   async inspectRetainedMutations(): Promise<PendingMutationInspection[]> {
     try {
       return parseNativeArray(
@@ -1046,6 +1145,23 @@ export class SynchroClient {
     }
   }
 
+  /** Returns every retained queue record in its stored representation. */
+  async inspectRetainedMutationRecords(): Promise<RetainedMutationInspection[]> {
+    try {
+      return parseNativeArray(
+        await this.native.inspectRetainedMutationRecords(),
+        'retained mutation inspection'
+      ).map(parseRetainedMutationInspection);
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  /**
+   * Returns the retained terminal outcomes.
+   * @deprecated Use {@link SynchroClient.inspectRejectedMutationRecords}. This method keeps its
+   * published behavior. It rejects when a legacy rejection is present.
+   */
   async inspectRejectedMutations(): Promise<RejectedMutationInspection[]> {
     try {
       return parseNativeArray(
@@ -1057,6 +1173,18 @@ export class SynchroClient {
     }
   }
 
+  /** Returns the retained terminal outcomes in their stored representation. */
+  async inspectRejectedMutationRecords(): Promise<RetainedRejectionInspection[]> {
+    try {
+      return parseNativeArray(
+        await this.native.inspectRejectedMutationRecords(),
+        'rejected mutation inspection'
+      ).map(parseRetainedRejectionInspection);
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
   async clearRejectedMutations(): Promise<void> {
     try {
       await this.native.clearRejectedMutations();

package/src/errors.ts

@@ -33,6 +33,7 @@ export const NATIVE_ERROR_CODES = [
   'TRANSACTION_TIMEOUT',
   'INVALID_CONFIG',
   'CLIENT_ALREADY_ACTIVE',
+  'atomic_group_invalid',
   'UNKNOWN',
 ] as const;
 
@@ -233,6 +234,25 @@ export class TransactionTimeoutError extends SynchroError {
   }
 }
 
+export const ATOMIC_GROUP_INVALID_REASONS = [
+  'deleteFollowedByWrite',
+  'tooManyMutations',
+  'mutationTooLarge',
+  'requestTooLarge',
+] as const;
+
+export type AtomicGroupInvalidReason = (typeof ATOMIC_GROUP_INVALID_REASONS)[number];
+
+export class AtomicGroupInvalidError extends SynchroError {
+  readonly reason: AtomicGroupInvalidReason;
+
+  constructor(reason: AtomicGroupInvalidReason) {
+    super('atomic_group_invalid', `Atomic write group is invalid: ${reason}`);
+    this.name = 'AtomicGroupInvalidError';
+    this.reason = reason;
+  }
+}
+
 interface NativeErrorLike {
   code?: string;
   message?: string;
@@ -439,6 +459,16 @@ export function mapNativeError(error: unknown): SynchroError {
       return new TransactionTimeoutError();
     case 'INVALID_CONFIG':
       return new SynchroError('INVALID_CONFIG', message);
+    case 'atomic_group_invalid':
+      try {
+        return new AtomicGroupInvalidError(
+          requiredEnum(userInfo.reason, ATOMIC_GROUP_INVALID_REASONS, 'atomic group invalid reason')
+        );
+      } catch (parseError) {
+        return parseError instanceof SynchroError
+          ? parseError
+          : new InvalidResponseError('Native bridge returned invalid atomic group details');
+      }
     default:
       return new SynchroError('UNKNOWN', message);
   }

package/src/index.ts

@@ -30,7 +30,11 @@ export type {
   SchemaRef,
   AuthoredMutationField,
   PendingMutationInspection,
+  LegacyMutationInspection,
+  RetainedMutationInspection,
   RejectedMutationInspection,
+  LegacyRejectionInspection,
+  RetainedRejectionInspection,
   SchemaAction,
   SyncSchemaEvent,
   SyncMutationEvent,
@@ -71,6 +75,8 @@ export {
   AlreadyStartedError,
   NotStartedError,
   TransactionTimeoutError,
+  AtomicGroupInvalidError,
+  ATOMIC_GROUP_INVALID_REASONS,
   NATIVE_ERROR_CODES,
   mapNativeError,
 } from './errors';
@@ -78,5 +84,6 @@ export {
 export type {
   NativeErrorCode,
   SchemaUnsupportedReason,
+  AtomicGroupInvalidReason,
   PushRejectedMutation,
 } from './errors';

package/src/inspection.ts

@@ -2,12 +2,19 @@ import {
   configureInspection,
   nativeForInspection,
   parseClientStateInspection,
+  parseRetainedMutationInspection,
+  parseRetainedRejectionInspection,
   parseTransportObservationSnapshot,
   SynchroClient,
 } from './SynchroClient';
 import { InvalidResponseError, mapNativeError } from './errors';
+import { assertValidSQLiteBindParams } from './sqliteValues';
 import type {
   ClientStateInspection,
+  RetainedMutationInspection,
+  RetainedRejectionInspection,
+  Row,
+  SQLStatement,
   TransportObservationSnapshot,
   TransportOperationClass,
 } from './types';
@@ -45,6 +52,18 @@ export interface DurableStateInspection {
   }>;
 }
 
+/**
+ * One read-only snapshot of client state and retained details. A detail list is
+ * null when its record count exceeds the native capture bound. `applicationRows`
+ * holds the rows that the requested read statements returned inside the snapshot.
+ */
+export interface ClientStateSnapshotInspection {
+  clientState: ClientStateInspection;
+  retainedMutations: RetainedMutationInspection[] | null;
+  rejectedMutations: RetainedRejectionInspection[] | null;
+  applicationRows: Row[];
+}
+
 export interface SynchroInspectionOptions {
   transportObservationCapacity?: number;
   requireNewDatabase?: boolean;
@@ -62,9 +81,22 @@ export class SynchroInspection {
     );
   }
 
-  async clientState(): Promise<ClientStateInspection> {
+  async captureSnapshot(rowStatements: SQLStatement[] = []): Promise<ClientStateSnapshotInspection> {
     try {
-      return parseClientStateInspection(parseJSON(await nativeForInspection(this.client).inspectClientState()));
+      const statements = rowStatements.map((statement) => ({
+        sql: statement.sql,
+        params: assertValidSQLiteBindParams(statement.params ?? []),
+      }));
+      const result = await nativeForInspection(this.client).inspectClientStateSnapshot(statements);
+      const snapshot = requireRecord(parseJSON(result.inspection), 'client state snapshot');
+      return {
+        clientState: parseClientStateInspection(snapshot.client_state),
+        retainedMutations:
+          nullableArray(snapshot.retained_mutations, 'retained mutations')?.map(parseRetainedMutationInspection) ?? null,
+        rejectedMutations:
+          nullableArray(snapshot.rejected_mutations, 'rejected mutations')?.map(parseRetainedRejectionInspection) ?? null,
+        applicationRows: [...result.applicationRows] as Row[],
+      };
     } catch (error) {
       throw mapNativeError(error);
     }
@@ -187,6 +219,16 @@ function parseDurableState(value: unknown): DurableStateInspection {
   return proof as unknown as DurableStateInspection;
 }
 
+function nullableArray(value: unknown, name: string): unknown[] | null {
+  if (value === null) {
+    return null;
+  }
+  if (!Array.isArray(value)) {
+    throw new InvalidResponseError(`Native bridge returned invalid ${name}`);
+  }
+  return value;
+}
+
 function requireRecord(value: unknown, name: string): Record<string, unknown> {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     throw new InvalidResponseError(`Native bridge returned invalid ${name}`);

package/src/types.ts

@@ -173,7 +173,8 @@ export type LocalMutationStatus =
   | 'superseded_before_send'
   | 'cancelled_before_send'
   | 'blocked_by_predecessor'
-  | 'server_rejected';
+  | 'server_rejected'
+  | 'exceeds_push_limit';
 
 export type MutationStatus = 'applied' | 'conflict' | 'rejected_terminal';
 
@@ -185,7 +186,8 @@ export type MutationRejectionCode =
   | 'schema_incompatible'
   | 'policy_rejected'
   | 'validation_failed'
-  | 'table_not_synced';
+  | 'table_not_synced'
+  | 'atomic_batch_rejected';
 
 export interface SchemaRef {
   version: number;
@@ -198,6 +200,7 @@ export interface AuthoredMutationField {
   value: JSONValue;
 }
 
+/** A retained mutation with its complete ledger binding and authored values. */
 export interface PendingMutationInspection {
   mutationID: string;
   localOrder: number;
@@ -219,6 +222,29 @@ export interface PendingMutationInspection {
   authoredFields: AuthoredMutationField[];
 }
 
+/**
+ * A retained mutation that a queue from before the mutation ledger imported.
+ * It has only the fields that the old queue stored.
+ */
+export interface LegacyMutationInspection {
+  representation: 'legacy';
+  mutationID: string;
+  localOrder: number;
+  tableName: string;
+  recordID: string;
+  operation: MutationOperation;
+  baseVersion: string | null;
+  clientVersion: string;
+  status: LocalMutationStatus;
+  sourceKind: string;
+}
+
+/** One retained mutation in its stored representation. */
+export type RetainedMutationInspection =
+  | (PendingMutationInspection & { representation: 'current' })
+  | LegacyMutationInspection;
+
+/** A retained rejection with its exact mutation and rejection JSON. */
 export interface RejectedMutationInspection {
   mutationID: string;
   tableName: string;
@@ -234,6 +260,29 @@ export interface RejectedMutationInspection {
   updatedAt: string;
 }
 
+/**
+ * A retained rejection that a database from before the mutation ledger stored.
+ * It has only the fields that the old rejection table stored.
+ */
+export interface LegacyRejectionInspection {
+  representation: 'legacy';
+  mutationID: string;
+  tableName: string;
+  recordID: string;
+  status: MutationStatus;
+  code: MutationRejectionCode;
+  message: string | null;
+  serverRowJSON: string | null;
+  serverVersion: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** One retained rejection in its stored representation. */
+export type RetainedRejectionInspection =
+  | (RejectedMutationInspection & { representation: 'current' })
+  | LegacyRejectionInspection;
+
 export interface ScopeStateInspection {
   scopeID: string;
   cursor: string | null;