More doc cleanup

Author: stevensJourney

packages/powersync-db-collection/src/PendingOperationStore.ts

@@ -13,7 +13,7 @@ export type PendingOperation = {
  * Optimistic mutations have their optimistic state discarded once transactions have
  * been applied.
  * We need to ensure that an applied transaction has been observed by the sync diff trigger
- * before resoling the transaction application call.
+ * before resolving the transaction application call.
  * This store allows registering a wait for a pending operation to have been observed.
  */
 export class PendingOperationStore {

packages/powersync-db-collection/src/PowerSyncTransactor.ts

@@ -1,11 +1,11 @@
 import { sanitizeSQL } from "@powersync/common"
 import DebugModule from "debug"
-import { PendingOperationStore } from "./PendingOperationStore"
 import { asPowerSyncRecord, mapOperationToPowerSync } from "./helpers"
+import { PendingOperationStore } from "./PendingOperationStore"
+import type { AbstractPowerSyncDatabase, LockContext } from "@powersync/common"
+import type { PendingMutation, Transaction } from "@tanstack/db"
 import type { EnhancedPowerSyncCollectionConfig } from "./definitions"
 import type { PendingOperation } from "./PendingOperationStore"
-import type { PendingMutation, Transaction } from "@tanstack/db"
-import type { AbstractPowerSyncDatabase, LockContext } from "@powersync/common"
 
 const debug = DebugModule.debug(`ts/db:powersync`)
 
@@ -29,16 +29,16 @@ export type TransactorOptions = {
  * )
  *
  * const addTx = createTransaction({
- *     autoCommit: false,
- *     mutationFn: async ({ transaction }) => {
- *         await new PowerSyncTransactor({database: db}).applyTransaction(transaction)
- *     },
+ *   autoCommit: false,
+ *   mutationFn: async ({ transaction }) => {
+ *     await new PowerSyncTransactor({ database: db }).applyTransaction(transaction)
+ *   },
  * })
  *
  * addTx.mutate(() => {
- *     for (let i = 0; i < 5; i++) {
- *        collection.insert({ id: randomUUID(), name: `tx-${i}` })
- *     }
+ *   for (let i = 0; i < 5; i++) {
+ *     collection.insert({ id: randomUUID(), name: `tx-${i}` })
+ *   }
  * })
  *
  * await addTx.commit()
@@ -58,7 +58,7 @@ export class PowerSyncTransactor<T extends object = Record<string, unknown>> {
   }
 
   /**
-   * Persists a {@link Transaction} to PowerSync's SQLite DB.
+   * Persists a {@link Transaction} to the PowerSync SQLite database.
    */
   async applyTransaction(transaction: Transaction<T>) {
     const { mutations } = transaction
@@ -67,8 +67,8 @@ export class PowerSyncTransactor<T extends object = Record<string, unknown>> {
       return
     }
     /**
-     * The transaction might contain ops for different collections.
-     * We can do some optimizations for single collection transactions.
+     * The transaction might contain operations for different collections.
+     * We can do some optimizations for single-collection transactions.
      */
     const mutationsCollectionIds = mutations.map(
       (mutation) => mutation.collection.id
@@ -103,7 +103,7 @@ export class PowerSyncTransactor<T extends object = Record<string, unknown>> {
         for (const [index, mutation] of mutations.entries()) {
           /**
            * Each collection processes events independently. We need to make sure the
-           * last operation for each collection has been seen.
+           * last operation for each collection has been observed.
            */
           const shouldWait =
             index == lastCollectionMutationIndexes.get(mutation.collection.id)
@@ -130,7 +130,7 @@ export class PowerSyncTransactor<T extends object = Record<string, unknown>> {
          * Return a promise from the writeTransaction, without awaiting it.
          * This promise will resolve once the entire transaction has been
          * observed via the diff triggers.
-         * We return without awaiting in order to free the writeLock.
+         * We return without awaiting in order to free the write lock.
          */
         return {
           whenComplete: Promise.all(
@@ -231,7 +231,7 @@ export class PowerSyncTransactor<T extends object = Record<string, unknown>> {
    * Helper function which wraps a persistence operation by:
    * - Fetching the mutation's collection's SQLite table details
    * - Executing the mutation
-   * - Returning the last pending diff op if required
+   * - Returning the last pending diff operation if required
    */
   protected async handleOperationWithCompletion(
     mutation: PendingMutation<T>,

packages/powersync-db-collection/src/definitions.ts

@@ -4,9 +4,9 @@ import type { BaseCollectionConfig, CollectionConfig } from "@tanstack/db"
 import type { ExtractedTable } from "./helpers"
 
 /**
- * Configuration interface for PowerSync collection options
+ * Configuration interface for PowerSync collection options.
  * @template TTable - The PowerSync table schema definition
- * @template TSchema - The schema type for validation
+ * @template TSchema - The validation schema type
  */
 /**
  * Configuration options for creating a PowerSync collection.
@@ -41,7 +41,7 @@ export type PowerSyncCollectionConfig<
   BaseCollectionConfig<ExtractedTable<TTable>, string, TSchema>,
   `onInsert` | `onUpdate` | `onDelete` | `getKey`
 > & {
-  /** The PowerSync Schema Table definition */
+  /** The PowerSync schema Table definition */
   table: TTable
   /** The PowerSync database instance */
   database: AbstractPowerSyncDatabase
@@ -61,21 +61,21 @@ export type PowerSyncCollectionConfig<
 }
 
 /**
- * Meta data for the PowerSync Collection
+ * Metadata for the PowerSync Collection.
  */
 export type PowerSyncCollectionMeta = {
   /**
    * The SQLite table representing the collection.
    */
   tableName: string
   /**
-   * The internal table used to track diff for the collection.
+   * The internal table used to track diffs for the collection.
    */
   trackedTableName: string
 }
 
 /**
- * A CollectionConfig which includes utilities for PowerSync
+ * A CollectionConfig which includes utilities for PowerSync.
  */
 export type EnhancedPowerSyncCollectionConfig<
   TTable extends Table = Table,
@@ -87,13 +87,13 @@ export type EnhancedPowerSyncCollectionConfig<
 }
 
 /**
- * Collection level utilities for PowerSync
+ * Collection-level utilities for PowerSync.
  */
 export type PowerSyncCollectionUtils = {
   getMeta: () => PowerSyncCollectionMeta
 }
 
 /**
- * Default value for {@link PowerSyncCollectionConfig#syncBatchSize}
+ * Default value for {@link PowerSyncCollectionConfig#syncBatchSize}.
  */
 export const DEFAULT_BATCH_SIZE = 1000

packages/powersync-db-collection/src/helpers.ts

@@ -2,18 +2,18 @@ import { DiffTriggerOperation } from "@powersync/common"
 import type { ExtractColumnValueType, Table } from "@powersync/common"
 
 /**
- * All PowerSync table records have a uuid `id` column.
+ * All PowerSync table records include a UUID `id` column.
  */
 export type PowerSyncRecord = {
   id: string
   [key: string]: unknown
 }
 
 /**
- * Utility type: If T includes null, add undefined.
- * PowerSync records typically are typed as `string | null`, where insert
- * and update operations also allow not specifying a value at all (optional)
- *  */
+ * Utility type: If T includes null, also allow undefined (to support optional fields in insert/update operations).
+ * PowerSync records are typically typed as `string | null`, where insert
+ * and update operations may also allow not specifying a value at all (optional).
+ */
 type WithUndefinedIfNull<T> = null extends T ? T | undefined : T
 type OptionalIfUndefined<T> = {
   [K in keyof T as undefined extends T[K] ? K : never]?: T[K]

packages/powersync-db-collection/src/powersync.ts

@@ -16,10 +16,10 @@ import type { ExtractedTable } from "./helpers"
 import type { PendingOperation } from "./PendingOperationStore"
 
 /**
- * Creates PowerSync collection options for use with a standard Collection
+ * Creates PowerSync collection options for use with a standard Collection.
  *
- * @template TTable - The SQLite based typing
- * @template TSchema - The schema type for validation - optionally supports a custom input type
+ * @template TTable - The SQLite-based typing
+ * @template TSchema - The validation schema type (optionally supports a custom input type)
  * @param config - Configuration options for the PowerSync collection
  * @returns Collection options with utilities
  */
@@ -66,7 +66,7 @@ export function powerSyncCollectionOptions<TTable extends Table = Table>(
  * ```typescript
  * import { z } from "zod"
  *
- * // The PowerSync SQLite Schema
+ * // The PowerSync SQLite schema
  * const APP_SCHEMA = new Schema({
  *   documents: new Table({
  *     name: column.text,
@@ -76,8 +76,8 @@ export function powerSyncCollectionOptions<TTable extends Table = Table>(
  * // Advanced Zod validations. The output type of this schema
  * // is constrained to the SQLite schema of APP_SCHEMA
  * const schema = z.object({
- *    id: z.string(),
- *    name: z.string().min(3, { message: "Should be at least 3 characters" }).nullable(),
+ *   id: z.string(),
+ *   name: z.string().min(3, { message: "Should be at least 3 characters" }).nullable(),
  * })
  *
  * const collection = createCollection(
@@ -122,9 +122,9 @@ export function powerSyncCollectionOptions<
   // We can do basic runtime validations for columns if not explicit schema has been provided
   const schema = inputSchema ?? (convertTableToSchema(table) as TSchema)
   /**
-   * The onInsert, onUpdate, onDelete handlers should only return
-   * after we have written the changes to Tanstack DB.
-   * We currently only write to Tanstack DB from a diff trigger.
+   * The onInsert, onUpdate, and onDelete handlers should only return
+   * after we have written the changes to TanStack DB.
+   * We currently only write to TanStack DB from a diff trigger.
    * We wait for the diff trigger to observe the change,
    * and only then return from the on[X] handlers.
    * This ensures that when the transaction is reported as

packages/powersync-db-collection/src/schema.ts

@@ -8,9 +8,9 @@ import type { ExtractedTable } from "./helpers"
  * Creates a schema that validates the structure and types of table records
  * according to the PowerSync table definition.
  *
- * @template TTable - The PowerSync schema typed Table definition
+ * @template TTable - The PowerSync schema-typed Table definition
  * @param table - The PowerSync Table instance to convert
- * @returns A StandardSchemaV1 compatible schema with proper type validation
+ * @returns A StandardSchemaV1-compatible schema with proper type validation
  *
  * @example
  * ```typescript