Add grid find method

spec/core/HGrid.spec.ts

@@ -1324,6 +1324,27 @@ type,val
 			})
 		}) // #any()
 
+		describe('#find()', function (): void {
+			it('returns the row dict for a match', function (): void {
+				expect(grid.find('foo')?.toJSON()).toEqual({ foo: 'foo' })
+			})
+
+			it('returns true for a match when using a node', function (): void {
+				const node = HFilter.parse('foo')
+				expect(grid.find(node)?.toJSON()).toEqual({ foo: 'foo' })
+			})
+
+			it('returns false when there is not a match', function (): void {
+				expect(grid.find('food')).toBeUndefined()
+			})
+
+			it('throws an error when the filter is invalid', function (): void {
+				expect((): void => {
+					grid.find('foo = true')
+				}).toThrow()
+			})
+		}) // #find()
+
 		describe('#matches()', function (): void {
 			it('returns true for a match', function (): void {
 				expect(grid.matches('foo')).toBe(true)

src/core/HGrid.ts

@@ -1282,6 +1282,41 @@ export class HGrid<DictVal extends HDict = HDict>
 		return result
 	}
 
+	/**
+	 * Return the first row dict that matches the filter or undefined if nothing is found.
+	 *
+	 * ```typescript
+	 * const dict = grid.find('site'))
+	 * ```
+	 *
+	 * @param filter The haystack filter or AST node.
+	 * @param cx Optional haystack filter evaluation context.
+	 * @returns The first row dict that matches the filter.
+	 */
+	public find(
+		filter: string | Node,
+		cx?: Partial<EvalContext>
+	): DictVal | undefined {
+		let result: DictVal | undefined
+
+		this.runFilter(
+			filter,
+			(match: boolean, row: DictVal): boolean => {
+				if (match) {
+					result = row
+
+					// Stop iterating since we have one match.
+					return false
+				}
+
+				// Keep iterating.
+				return true
+			},
+			cx
+		)
+		return result
+	}
+
 	/**
 	 * Returns true if the haystack filter matches the value.
 	 *