@quereus/quereus 0.6.5 → 0.6.7

package/src/planner/building/constraint-builder.ts

@@ -1,178 +1,178 @@
-import type { PlanningContext } from '../planning-context.js';
-import type { TableSchema, RowConstraintSchema } from '../../schema/table.js';
-import type { RowOpFlag } from '../../schema/table.js';
-import type { Attribute, RowDescriptor } from '../nodes/plan-node.js';
-import type { ConstraintCheck } from '../nodes/constraint-check-node.js';
-import { RegisteredScope } from '../scopes/registered.js';
-import { buildExpression } from './expression.js';
-import { PlanNodeType } from '../nodes/plan-node-type.js';
-import { ColumnReferenceNode } from '../nodes/reference.js';
-import type { ScalarPlanNode } from '../nodes/plan-node.js';
-import * as AST from '../../parser/ast.js';
-import { validateDeterministicConstraint } from '../validation/determinism-validator.js';
-
-/**
- * Determines if a constraint should be checked for the given operation
- */
-function shouldCheckConstraint(constraint: RowConstraintSchema, operation: RowOpFlag): boolean {
-  // Check if the current operation is in the constraint's operations bitmask
-  return (constraint.operations & operation) !== 0;
-}
-
-/**
- * Builds constraint check expressions at plan time.
- * This allows the optimizer to see and optimize constraint expressions.
- */
-export function buildConstraintChecks(
-  ctx: PlanningContext,
-  tableSchema: TableSchema,
-  operation: RowOpFlag,
-  oldAttributes: Attribute[],
-  newAttributes: Attribute[],
-  _flatRowDescriptor: RowDescriptor,
-  contextAttributes: Attribute[] = []
-): ConstraintCheck[] {
-  // Build attribute ID mappings for column registration
-  const newAttrIdByCol: Record<string, number> = {};
-  const oldAttrIdByCol: Record<string, number> = {};
-
-  newAttributes.forEach((attr, columnIndex) => {
-    if (columnIndex < tableSchema.columns.length) {
-      const column = tableSchema.columns[columnIndex];
-      newAttrIdByCol[column.name.toLowerCase()] = attr.id;
-    }
-  });
-
-  oldAttributes.forEach((attr, columnIndex) => {
-    if (columnIndex < tableSchema.columns.length) {
-      const column = tableSchema.columns[columnIndex];
-      oldAttrIdByCol[column.name.toLowerCase()] = attr.id;
-    }
-  });
-
-  // Filter constraints by operation
-  const applicableConstraints = tableSchema.checkConstraints
-    .filter(constraint => shouldCheckConstraint(constraint, operation));
-
-  // Build expression nodes for each constraint
-  return applicableConstraints.map(constraint => {
-    // Create scope with OLD/NEW column access for constraint evaluation
-    const constraintScope = new RegisteredScope(ctx.scope);
-
-    // Register mutation context variables FIRST (so they shadow column names if conflicts exist)
-    contextAttributes.forEach((attr, contextVarIndex) => {
-      if (contextVarIndex < (tableSchema.mutationContext?.length || 0)) {
-        const contextVar = tableSchema.mutationContext![contextVarIndex];
-        const varNameLower = contextVar.name.toLowerCase();
-
-        // Register both unqualified and qualified names
-        constraintScope.subscribeFactory(varNameLower, (exp, s) =>
-          new ColumnReferenceNode(s, exp as AST.ColumnExpr, attr.type, attr.id, contextVarIndex)
-        );
-        constraintScope.subscribeFactory(`context.${varNameLower}`, (exp, s) =>
-          new ColumnReferenceNode(s, exp as AST.ColumnExpr, attr.type, attr.id, contextVarIndex)
-        );
-      }
-    });
-
-    // Register column symbols (similar to current emitConstraintCheck logic)
-    tableSchema.columns.forEach((tableColumn, tableColIndex) => {
-      const colNameLower = tableColumn.name.toLowerCase();
-
-      // Register NEW.col and unqualified col (defaults to NEW for INSERT/UPDATE, OLD for DELETE)
-      const newAttrId = newAttrIdByCol[colNameLower];
-      if (newAttrId !== undefined) {
-        const newColumnType = {
-          typeClass: 'scalar' as const,
-          logicalType: tableColumn.logicalType,
-          nullable: !tableColumn.notNull,
-          isReadOnly: false
-        };
-
-        // NEW.column
-        constraintScope.registerSymbol(`new.${colNameLower}`, (exp, s) =>
-          new ColumnReferenceNode(s, exp as AST.ColumnExpr, newColumnType, newAttrId, tableColIndex));
-
-        // For INSERT/UPDATE, unqualified column defaults to NEW
-        if (operation === 1 || operation === 2) { // INSERT or UPDATE
-          constraintScope.registerSymbol(colNameLower, (exp, s) =>
-            new ColumnReferenceNode(s, exp as AST.ColumnExpr, newColumnType, newAttrId, tableColIndex));
-        }
-      }
-
-      // Register OLD.col
-      const oldAttrId = oldAttrIdByCol[colNameLower];
-      if (oldAttrId !== undefined) {
-        const oldColumnType = {
-          typeClass: 'scalar' as const,
-          logicalType: tableColumn.logicalType,
-          nullable: true, // OLD values can be NULL (especially for INSERT)
-          isReadOnly: false
-        };
-
-        // OLD.column
-        constraintScope.registerSymbol(`old.${colNameLower}`, (exp, s) =>
-          new ColumnReferenceNode(s, exp as AST.ColumnExpr, oldColumnType, oldAttrId, tableColIndex));
-
-        // For DELETE, unqualified column defaults to OLD
-        if (operation === 4) { // DELETE
-          constraintScope.registerSymbol(colNameLower, (exp, s) =>
-            new ColumnReferenceNode(s, exp as AST.ColumnExpr, oldColumnType, oldAttrId, tableColIndex));
-        }
-      }
-    });
-
-    // Build the constraint expression using the specialized scope
-    // Temporarily set the current schema to match the table's schema
-    // This ensures unqualified table references in CHECK constraints resolve correctly
-    const originalCurrentSchema = ctx.schemaManager.getCurrentSchemaName();
-    const needsSchemaSwitch = tableSchema.schemaName !== originalCurrentSchema;
-
-    if (needsSchemaSwitch) {
-      ctx.schemaManager.setCurrentSchema(tableSchema.schemaName);
-    }
-
-    try {
-      const expression = buildExpression(
-        { ...ctx, scope: constraintScope },
-        constraint.expr
-      ) as ScalarPlanNode;
-
-      // Validate that the constraint expression is deterministic
-      const constraintName = constraint.name ?? `_check_${tableSchema.name}`;
-      validateDeterministicConstraint(expression, constraintName, tableSchema.name);
-
-      // Heuristic: auto-defer if the expression contains a subquery
-      // or references a different relation via attribute bindings (NEW/OLD already localized).
-      const needsDeferred = containsSubquery(expression);
-
-      return {
-        constraint,
-        expression,
-        deferrable: needsDeferred,
-        initiallyDeferred: needsDeferred,
-        containsSubquery: needsDeferred
-      } satisfies ConstraintCheck;
-    } finally {
-      // Restore original schema context
-      if (needsSchemaSwitch) {
-        ctx.schemaManager.setCurrentSchema(originalCurrentSchema);
-      }
-    }
-  });
-}
-
-function containsSubquery(expr: ScalarPlanNode): boolean {
-  const stack: ScalarPlanNode[] = [expr];
-  while (stack.length) {
-    const n = stack.pop()!;
-    if (n.nodeType === PlanNodeType.ScalarSubquery || n.nodeType === PlanNodeType.Exists) {
-      return true;
-    }
-    for (const c of n.getChildren()) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      stack.push(c as any);
-    }
-  }
-  return false;
-}
+import type { PlanningContext } from '../planning-context.js';
+import type { TableSchema, RowConstraintSchema } from '../../schema/table.js';
+import type { RowOpFlag } from '../../schema/table.js';
+import type { Attribute, RowDescriptor } from '../nodes/plan-node.js';
+import type { ConstraintCheck } from '../nodes/constraint-check-node.js';
+import { RegisteredScope } from '../scopes/registered.js';
+import { buildExpression } from './expression.js';
+import { PlanNodeType } from '../nodes/plan-node-type.js';
+import { ColumnReferenceNode } from '../nodes/reference.js';
+import type { ScalarPlanNode } from '../nodes/plan-node.js';
+import * as AST from '../../parser/ast.js';
+import { validateDeterministicConstraint } from '../validation/determinism-validator.js';
+
+/**
+ * Determines if a constraint should be checked for the given operation
+ */
+function shouldCheckConstraint(constraint: RowConstraintSchema, operation: RowOpFlag): boolean {
+  // Check if the current operation is in the constraint's operations bitmask
+  return (constraint.operations & operation) !== 0;
+}
+
+/**
+ * Builds constraint check expressions at plan time.
+ * This allows the optimizer to see and optimize constraint expressions.
+ */
+export function buildConstraintChecks(
+  ctx: PlanningContext,
+  tableSchema: TableSchema,
+  operation: RowOpFlag,
+  oldAttributes: Attribute[],
+  newAttributes: Attribute[],
+  _flatRowDescriptor: RowDescriptor,
+  contextAttributes: Attribute[] = []
+): ConstraintCheck[] {
+  // Build attribute ID mappings for column registration
+  const newAttrIdByCol: Record<string, number> = {};
+  const oldAttrIdByCol: Record<string, number> = {};
+
+  newAttributes.forEach((attr, columnIndex) => {
+    if (columnIndex < tableSchema.columns.length) {
+      const column = tableSchema.columns[columnIndex];
+      newAttrIdByCol[column.name.toLowerCase()] = attr.id;
+    }
+  });
+
+  oldAttributes.forEach((attr, columnIndex) => {
+    if (columnIndex < tableSchema.columns.length) {
+      const column = tableSchema.columns[columnIndex];
+      oldAttrIdByCol[column.name.toLowerCase()] = attr.id;
+    }
+  });
+
+  // Filter constraints by operation
+  const applicableConstraints = tableSchema.checkConstraints
+    .filter(constraint => shouldCheckConstraint(constraint, operation));
+
+  // Build expression nodes for each constraint
+  return applicableConstraints.map(constraint => {
+    // Create scope with OLD/NEW column access for constraint evaluation
+    const constraintScope = new RegisteredScope(ctx.scope);
+
+    // Register mutation context variables FIRST (so they shadow column names if conflicts exist)
+    contextAttributes.forEach((attr, contextVarIndex) => {
+      if (contextVarIndex < (tableSchema.mutationContext?.length || 0)) {
+        const contextVar = tableSchema.mutationContext![contextVarIndex];
+        const varNameLower = contextVar.name.toLowerCase();
+
+        // Register both unqualified and qualified names
+        constraintScope.subscribeFactory(varNameLower, (exp, s) =>
+          new ColumnReferenceNode(s, exp as AST.ColumnExpr, attr.type, attr.id, contextVarIndex)
+        );
+        constraintScope.subscribeFactory(`context.${varNameLower}`, (exp, s) =>
+          new ColumnReferenceNode(s, exp as AST.ColumnExpr, attr.type, attr.id, contextVarIndex)
+        );
+      }
+    });
+
+    // Register column symbols (similar to current emitConstraintCheck logic)
+    tableSchema.columns.forEach((tableColumn, tableColIndex) => {
+      const colNameLower = tableColumn.name.toLowerCase();
+
+      // Register NEW.col and unqualified col (defaults to NEW for INSERT/UPDATE, OLD for DELETE)
+      const newAttrId = newAttrIdByCol[colNameLower];
+      if (newAttrId !== undefined) {
+        const newColumnType = {
+          typeClass: 'scalar' as const,
+          logicalType: tableColumn.logicalType,
+          nullable: !tableColumn.notNull,
+          isReadOnly: false
+        };
+
+        // NEW.column
+        constraintScope.registerSymbol(`new.${colNameLower}`, (exp, s) =>
+          new ColumnReferenceNode(s, exp as AST.ColumnExpr, newColumnType, newAttrId, tableColIndex));
+
+        // For INSERT/UPDATE, unqualified column defaults to NEW
+        if (operation === 1 || operation === 2) { // INSERT or UPDATE
+          constraintScope.registerSymbol(colNameLower, (exp, s) =>
+            new ColumnReferenceNode(s, exp as AST.ColumnExpr, newColumnType, newAttrId, tableColIndex));
+        }
+      }
+
+      // Register OLD.col
+      const oldAttrId = oldAttrIdByCol[colNameLower];
+      if (oldAttrId !== undefined) {
+        const oldColumnType = {
+          typeClass: 'scalar' as const,
+          logicalType: tableColumn.logicalType,
+          nullable: true, // OLD values can be NULL (especially for INSERT)
+          isReadOnly: false
+        };
+
+        // OLD.column
+        constraintScope.registerSymbol(`old.${colNameLower}`, (exp, s) =>
+          new ColumnReferenceNode(s, exp as AST.ColumnExpr, oldColumnType, oldAttrId, tableColIndex));
+
+        // For DELETE, unqualified column defaults to OLD
+        if (operation === 4) { // DELETE
+          constraintScope.registerSymbol(colNameLower, (exp, s) =>
+            new ColumnReferenceNode(s, exp as AST.ColumnExpr, oldColumnType, oldAttrId, tableColIndex));
+        }
+      }
+    });
+
+    // Build the constraint expression using the specialized scope
+    // Temporarily set the current schema to match the table's schema
+    // This ensures unqualified table references in CHECK constraints resolve correctly
+    const originalCurrentSchema = ctx.schemaManager.getCurrentSchemaName();
+    const needsSchemaSwitch = tableSchema.schemaName !== originalCurrentSchema;
+
+    if (needsSchemaSwitch) {
+      ctx.schemaManager.setCurrentSchema(tableSchema.schemaName);
+    }
+
+    try {
+      const expression = buildExpression(
+        { ...ctx, scope: constraintScope },
+        constraint.expr
+      ) as ScalarPlanNode;
+
+      // Validate that the constraint expression is deterministic
+      const constraintName = constraint.name ?? `_check_${tableSchema.name}`;
+      validateDeterministicConstraint(expression, constraintName, tableSchema.name);
+
+      // Heuristic: auto-defer if the expression contains a subquery
+      // or references a different relation via attribute bindings (NEW/OLD already localized).
+      const needsDeferred = containsSubquery(expression);
+
+      return {
+        constraint,
+        expression,
+        deferrable: needsDeferred,
+        initiallyDeferred: needsDeferred,
+        containsSubquery: needsDeferred
+      } satisfies ConstraintCheck;
+    } finally {
+      // Restore original schema context
+      if (needsSchemaSwitch) {
+        ctx.schemaManager.setCurrentSchema(originalCurrentSchema);
+      }
+    }
+  });
+}
+
+function containsSubquery(expr: ScalarPlanNode): boolean {
+  const stack: ScalarPlanNode[] = [expr];
+  while (stack.length) {
+    const n = stack.pop()!;
+    if (n.nodeType === PlanNodeType.ScalarSubquery || n.nodeType === PlanNodeType.Exists) {
+      return true;
+    }
+    for (const c of n.getChildren()) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      stack.push(c as any);
+    }
+  }
+  return false;
+}

package/src/planner/validation/determinism-validator.ts

@@ -1,76 +1,104 @@
-import { QuereusError } from '../../common/errors.js';
-import { StatusCode } from '../../common/types.js';
-import type { ScalarPlanNode } from '../nodes/plan-node.js';
-import { createLogger } from '../../common/logger.js';
-
-const log = createLogger('planner:validation:determinism');
-
-/**
- * Validates that an expression is deterministic (suitable for constraints and defaults).
- * Non-deterministic expressions must be passed via mutation context instead.
- *
- * @param expr The expression plan node to validate
- * @param context Description of where the expression is used (e.g., "DEFAULT for column 'created_at'")
- * @throws QuereusError if the expression is non-deterministic
- */
-export function validateDeterministicExpression(
-	expr: ScalarPlanNode,
-	context: string
-): void {
-	log('Validating determinism for: %s', context);
-
-	// Check physical properties - this will recursively check all child nodes
-	const physical = expr.physical;
-
-	if (physical.deterministic === false) {
-		log('Non-deterministic expression detected in %s: %s', context, expr.toString());
-
-		throw new QuereusError(
-			`Non-deterministic expression not allowed in ${context}. ` +
-			`Expression: ${expr.toString()}. ` +
-			`Use mutation context to pass non-deterministic values (e.g., WITH CONTEXT (timestamp = datetime('now'))).`,
-			StatusCode.ERROR
-		);
-	}
-
-	log('Expression is deterministic: %s', expr.toString());
-}
-
-/**
- * Validates that a CHECK constraint expression is deterministic.
- *
- * @param expr The constraint expression plan node
- * @param constraintName The name of the constraint (for error messages)
- * @param tableName The name of the table (for error messages)
- * @throws QuereusError if the expression is non-deterministic
- */
-export function validateDeterministicConstraint(
-	expr: ScalarPlanNode,
-	constraintName: string,
-	tableName: string
-): void {
-	validateDeterministicExpression(
-		expr,
-		`CHECK constraint '${constraintName}' on table '${tableName}'`
-	);
-}
-
-/**
- * Validates that a DEFAULT expression is deterministic.
- *
- * @param expr The default value expression plan node
- * @param columnName The name of the column (for error messages)
- * @param tableName The name of the table (for error messages)
- * @throws QuereusError if the expression is non-deterministic
- */
-export function validateDeterministicDefault(
-	expr: ScalarPlanNode,
-	columnName: string,
-	tableName: string
-): void {
-	validateDeterministicExpression(
-		expr,
-		`DEFAULT for column '${columnName}' in table '${tableName}'`
-	);
-}
-
+import { QuereusError } from '../../common/errors.js';
+import { StatusCode } from '../../common/types.js';
+import type { ScalarPlanNode } from '../nodes/plan-node.js';
+import { createLogger } from '../../common/logger.js';
+
+const log = createLogger('planner:validation:determinism');
+
+/**
+ * Result of determinism validation. If valid, `error` is undefined.
+ * If invalid, contains the information needed to construct an error message.
+ */
+export interface DeterminismValidationResult {
+	/** True if the expression is deterministic */
+	valid: boolean;
+	/** String representation of the offending expression (if invalid) */
+	expression?: string;
+}
+
+/**
+ * Checks if an expression is deterministic (suitable for constraints and defaults).
+ * Returns a result object instead of throwing, allowing the caller to decide how to handle.
+ *
+ * @param expr The expression plan node to check
+ * @returns Validation result indicating if deterministic
+ */
+export function checkDeterministic(expr: ScalarPlanNode): DeterminismValidationResult {
+	const physical = expr.physical;
+
+	if (physical.deterministic === false) {
+		log('Non-deterministic expression detected: %s', expr.toString());
+		return {
+			valid: false,
+			expression: expr.toString()
+		};
+	}
+
+	return { valid: true };
+}
+
+/**
+ * Validates that an expression is deterministic (suitable for constraints and defaults).
+ * Non-deterministic expressions must be passed via mutation context instead.
+ *
+ * @param expr The expression plan node to validate
+ * @param context Description of where the expression is used (e.g., "DEFAULT for column 'created_at'")
+ * @throws QuereusError if the expression is non-deterministic
+ */
+export function validateDeterministicExpression(
+	expr: ScalarPlanNode,
+	context: string
+): void {
+	log('Validating determinism for: %s', context);
+
+	const result = checkDeterministic(expr);
+
+	if (!result.valid) {
+		throw new QuereusError(
+			`Non-deterministic expression not allowed in ${context}. ` +
+			`Expression: ${result.expression}. ` +
+			`Use mutation context to pass non-deterministic values (e.g., WITH CONTEXT (timestamp = datetime('now'))).`,
+			StatusCode.ERROR
+		);
+	}
+
+	log('Expression is deterministic: %s', expr.toString());
+}
+
+/**
+ * Validates that a CHECK constraint expression is deterministic.
+ *
+ * @param expr The constraint expression plan node
+ * @param constraintName The name of the constraint (for error messages)
+ * @param tableName The name of the table (for error messages)
+ * @throws QuereusError if the expression is non-deterministic
+ */
+export function validateDeterministicConstraint(
+	expr: ScalarPlanNode,
+	constraintName: string,
+	tableName: string
+): void {
+	validateDeterministicExpression(
+		expr,
+		`CHECK constraint '${constraintName}' on table '${tableName}'`
+	);
+}
+
+/**
+ * Validates that a DEFAULT expression is deterministic.
+ *
+ * @param expr The default value expression plan node
+ * @param columnName The name of the column (for error messages)
+ * @param tableName The name of the table (for error messages)
+ * @throws QuereusError if the expression is non-deterministic
+ */
+export function validateDeterministicDefault(
+	expr: ScalarPlanNode,
+	columnName: string,
+	tableName: string
+): void {
+	validateDeterministicExpression(
+		expr,
+		`DEFAULT for column '${columnName}' in table '${tableName}'`
+	);
+}

package/src/runtime/async-util.ts

@@ -5,6 +5,7 @@
 
 import type { MaybePromise, Row } from '../common/types.js';
 import { createLogger } from '../common/logger.js';
+import { getAsyncIterator } from './utils.js';
 
 const log = createLogger('runtime:async-util');
 
@@ -52,7 +53,7 @@ export function tee<T>(src: AsyncIterable<T>): [AsyncIterable<T>, AsyncIterable<
 		}
 
 		if (!srcIterator) {
-			srcIterator = src[Symbol.asyncIterator]();
+			srcIterator = getAsyncIterator(src);
 		}
 
 		while (buffer.length <= targetIndex && !srcDone) {
@@ -124,7 +125,7 @@ export async function* buffered<T>(
 	maxBuffer: number
 ): AsyncIterable<T> {
 	const buffer: T[] = [];
-	const srcIterator = src[Symbol.asyncIterator]();
+	const srcIterator = getAsyncIterator(src);
 	let srcDone = false;
 	let fillPromise: Promise<void> | null = null;
 
@@ -217,7 +218,7 @@ export async function collect<T>(src: AsyncIterable<T>): Promise<T[]> {
  * Items are yielded as soon as they become available from any source
  */
 export async function* merge<T>(...sources: AsyncIterable<T>[]): AsyncIterable<T> {
-	const iterators = sources.map(src => src[Symbol.asyncIterator]());
+	const iterators = sources.map(src => getAsyncIterator(src));
 	const pending = new Map<number, Promise<IteratorResult<T>>>();
 
 	// Start initial reads

package/src/runtime/emitters.ts

@@ -7,6 +7,7 @@ import { StatusCode, type OutputValue } from '../common/types.js';
 import { createLogger } from '../common/logger.js';
 import { Scheduler } from "./scheduler.js";
 import type { EmissionContext } from "./emission-context.js";
+import { isAsyncIterable } from "./utils.js";
 
 const log = createLogger('emitters');
 
@@ -81,7 +82,7 @@ function instrumentRunForTracing(plan: PlanNode, originalRun: InstructionRun): I
 		}
 
 		// If the result is an async iterable, defer the pop until iteration completes
-		if (result && typeof result === 'object' && Symbol.asyncIterator in result) {
+		if (isAsyncIterable(result)) {
 			const iterable = result as AsyncIterable<unknown>;
 			// Wrap iterable to pop stack in a finally block once iteration ends
 			return (async function* () {

package/src/runtime/utils.ts

@@ -14,8 +14,48 @@ const log = createLogger('runtime:utils');
 const errorLog = log.extend('error');
 export const ctxLog = createLogger('runtime:context');
 
+/**
+ * Check if a value is an AsyncIterable.
+ * 
+ * NOTE: Hermes (React Native's JS engine) has a bug where AsyncGenerator objects
+ * don't have Symbol.asyncIterator as an own or inherited property, even though
+ * they are valid async iterables. We work around this by also checking for
+ * the presence of a .next() method (duck typing for async iterators).
+ */
 export function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {
-	return typeof value === 'object' && value !== null && Symbol.asyncIterator in value;
+	if (typeof value !== 'object' || value === null) {
+		return false;
+	}
+	// Standard check: Symbol.asyncIterator
+	if (Symbol.asyncIterator in value) {
+		return true;
+	}
+	// Hermes workaround: AsyncGenerator has .next() but not Symbol.asyncIterator
+	const maybeAsyncGen = value as { next?: unknown; constructor?: { name?: string } };
+	if (typeof maybeAsyncGen.next === 'function' && 
+	    maybeAsyncGen.constructor?.name === 'AsyncGenerator') {
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Get an AsyncIterator from an AsyncIterable, handling Hermes's missing Symbol.asyncIterator.
+ * 
+ * @throws TypeError if value is not a valid async iterable
+ */
+export function getAsyncIterator<T>(value: AsyncIterable<T>): AsyncIterator<T> {
+	// Standard path: use Symbol.asyncIterator
+	if (Symbol.asyncIterator in value) {
+		return value[Symbol.asyncIterator]();
+	}
+	// Hermes workaround: AsyncGenerator is its own iterator
+	const maybeAsyncGen = value as unknown as { next?: () => Promise<IteratorResult<T>>; constructor?: { name?: string } };
+	if (typeof maybeAsyncGen.next === 'function' && 
+	    maybeAsyncGen.constructor?.name === 'AsyncGenerator') {
+		return maybeAsyncGen as AsyncIterator<T>;
+	}
+	throw new TypeError('Value is not async iterable');
 }
 
 export async function asyncIterableToArray<T>(iterable: AsyncIterable<T>): Promise<T[]> {