fix(react-native): honor declared OP-SQLite envelopes

Author: KyleAMathews

packages/react-native-db-sqlite-persistence/src/op-sqlite-driver.ts

@@ -181,6 +181,23 @@ function toRowArray(rowsValue: unknown): Array<unknown> | null {
   return null
 }
 
+function isRowCarrier(rowsValue: unknown): boolean {
+  if (Array.isArray(rowsValue)) {
+    return true
+  }
+
+  if (!isObjectRecord(rowsValue)) {
+    return false
+  }
+
+  const rowsObject = rowsValue as OpSQLiteRowListLike
+  return (
+    Array.isArray(rowsObject._array) ||
+    (typeof rowsObject.length === `number` &&
+      typeof rowsObject.item === `function`)
+  )
+}
+
 function isStatementResultEnvelope(value: Record<string, unknown>): boolean {
   if (!Object.keys(value).every((key) => STATEMENT_RESULT_KEYS.has(key))) {
     return false
@@ -189,14 +206,17 @@ function isStatementResultEnvelope(value: Record<string, unknown>): boolean {
   // Bare arrays are also a supported row carrier. A legitimate row can contain
   // only write-marker aliases, so markers alone cannot prove that an array is a
   // statement wrapper; wrappers need an actual row structure.
+  const hasRowCarrier =
+    isRowCarrier(value.rows) ||
+    isRowCarrier(value.resultRows) ||
+    Array.isArray(value.results)
   const hasStructuralCarrier =
-    toRowArray(value.rows) !== null ||
-    toRowArray(value.resultRows) !== null ||
+    hasRowCarrier ||
     Array.isArray(value.rawRows) ||
-    Array.isArray(value.columnNames) ||
-    Array.isArray(value.results)
+    Array.isArray(value.columnNames)
 
   return (
+    hasRowCarrier ||
     (hasWriteResultMarker(value) && hasStructuralCarrier) ||
     (Array.isArray(value.rawRows) && Array.isArray(value.columnNames))
   )

packages/react-native-db-sqlite-persistence/tests/helpers/op-sqlite-test-db.ts

@@ -94,6 +94,7 @@ function formatWriteResult(
       return {
         rowsAffected,
         insertId,
+        rows: [],
       }
     default:
       return {

packages/react-native-db-sqlite-persistence/tests/op-sqlite-driver.test.ts

@@ -109,11 +109,13 @@ async function withColumnarDriver<T>(
  * their names match envelope fields, including direct rows made only of write
  * marker aliases. When OP-SQLite supplies object rows and raw columnar rows
  * together, the already-decoded object rows are authoritative. Malformed or
- * undocumented result carriers reject. A bare array whose first entry can be
+ * incomplete result carriers reject. A bare array whose first entry can be
  * both a row and a statement envelope has no self-describing interpretation;
- * its driver must declare `rows` or `statement-results` mode.
+ * its driver must declare `rows` or `statement-results` mode. The declared
+ * mode, rather than reserved field names, decides markerless `{ rows }`
+ * wrappers.
  * Source: SQLiteDriver's public query contract and op-sqlite's documented
- * execute `{ rows, columnNames }` and executeAsync
+ * required `QueryResult.rows`, execute `{ rows, columnNames }`, and executeAsync
  * `{ rawRows, columnNames, rowsAffected }` envelopes.
  * Domain: deterministic object-row wrappers and columnar rows, including
  * empty, asymmetric/reordered multirow, legal reserved-looking SQL aliases,
@@ -262,6 +264,37 @@ it(`requires an explicit mode for an ambiguous bare result array`, async () => {
   ).resolves.toEqual([`nested`])
 })
 
+it(`uses the declared mode for a markerless statement-array envelope`, async () => {
+  const ambiguous = [{ rows: [{ id: `nested-row` }] }]
+
+  await expect(queryInjectedResult(ambiguous)).rejects.toThrow(
+    `ambiguous bare result array`,
+  )
+  await expect(queryInjectedResult(ambiguous, `rows`)).resolves.toEqual(
+    ambiguous,
+  )
+  await expect(
+    queryInjectedResult(ambiguous, `statement-results`),
+  ).resolves.toEqual([{ id: `nested-row` }])
+})
+
+it(`materializes a declared statement row list exactly once`, async () => {
+  const expected = [{ id: `first` }, { id: `second` }]
+  const requestedIndexes: Array<number> = []
+  const rows = {
+    length: expected.length,
+    item: (index: number) => {
+      requestedIndexes.push(index)
+      return expected[index]
+    },
+  }
+
+  await expect(
+    queryInjectedResult([{ rowsAffected: 0, rows }], `statement-results`),
+  ).resolves.toEqual(expected)
+  expect(requestedIndexes).toEqual([0, 1])
+})
+
 it(`reads op-sqlite execute rows when columnNames metadata is also present`, async () => {
   await expect(
     queryInjectedResult({
@@ -701,7 +734,7 @@ const malformedColumnarResults: ReadonlyArray<{
     result: { mysteryRows: [[`1`]] },
   },
   {
-    name: `undocumented res carrier`,
+    name: `optional res field without the required rows carrier`,
     result: { rowsAffected: 0, res: [{ id: `legacy` }] },
   },
   {
@@ -770,6 +803,35 @@ it(`supports exactly one results wrapper`, async () => {
   expect(queryExecutions).toBe(1)
 })
 
+it(`rejects a multi-statement results wrapper instead of dropping results`, async () => {
+  await expect(
+    queryInjectedResult({
+      results: [
+        { rows: [{ id: `first-statement` }] },
+        { rows: [{ id: `second-statement` }] },
+      ],
+    }),
+  ).rejects.toThrow(`invalid nested results carrier`)
+})
+
+it(`models OP-SQLite writes with an empty rows carrier`, async () => {
+  const dbPath = createTempSqlitePath()
+  const database = createOpSQLiteTestDatabase({
+    filename: dbPath,
+    resultShape: `execute-async-columnar`,
+  })
+  activeCleanupFns.push(() => Promise.resolve(database.close()))
+  const executeAsync = database.executeAsync
+  if (!executeAsync) {
+    throw new Error(`columnar fixture must expose executeAsync`)
+  }
+
+  await executeAsync(`CREATE TABLE write_receipt (id INTEGER PRIMARY KEY)`)
+  await expect(
+    executeAsync(`INSERT INTO write_receipt (id) VALUES (?)`, [1]),
+  ).resolves.toMatchObject({ rowsAffected: 1, rows: [] })
+})
+
 it.each([
   {
     name: `second results wrapper`,