@orkestrel/database 0.0.18 → 0.0.19

package/dist/src/core/index.d.cts

@@ -89,6 +89,16 @@ export declare function auditDriver(factory: () => DriverInterface): Promise<rea
  */
 export declare function bindRowKey(row: Row, primary: string, key: Key): Row;
 
+/**
+ * Captures the exact rejection or synchronous throw from a driver conformance operation.
+ *
+ * @example
+ * ```ts
+ * await captureFailure(() => Promise.reject('refused')) // 'refused'
+ * ```
+ */
+export declare function captureFailure(operation: () => Promise<unknown>): Promise<unknown>;
+
 /**
  * Throws when an {@link OperationOptions.signal | AbortSignal} has fired — the shared
  * abort gate checked at operation boundaries and between streamed rows.
@@ -913,6 +923,11 @@ export declare function isColumnSchema(value: unknown): value is ColumnSchema;
 /**
  * Narrows an unknown caught value to a {@link DatabaseError}.
  *
+ * @remarks
+ * Accepts branded instances and subclasses across package copies and module formats.
+ * Requires the declared code and context shape. Refuses look-alikes and transparent
+ * proxies without requiring an exact `name`.
+ *
  * @param value - The value to test (typically a `catch` binding)
  * @returns True if `value` is a {@link DatabaseError}; false otherwise
  *
@@ -1122,19 +1137,20 @@ export declare function matchesQuery(row: Row, conditions: readonly Condition[])
  * `.*` segments separated by literals, matched against a long non-matching input, blow
  * up super-linearly — and JS has no atomic groups / possessive quantifiers to bound it,
  * while a `LIKE` / `GLOB` pattern is a caller-supplied operand this package cannot
- * trust. So this builds no regex. It runs the classic greedy two-pointer wildcard match:
- * the `any` wildcard records its position and, on a later mismatch, backtracks only to
- * that last `any` (letting it absorb one more char) — so the work is O(value × pattern),
- * never the exponential / polynomial backtracking a regex would do. The pattern length
- * is capped at {@link MAX_PATTERN_LENGTH} (a `VALIDATION` {@link DatabaseError} over it),
- * bounding the pattern factor so a match stays linear in the value length whatever the
- * pattern.
+ * trust. This builds no regex. It splits the pattern on `any` into fixed-length
+ * segments, anchors the first at the value's start and the last at its end, and places
+ * each middle segment at its leftmost match after the one before it, which is the only
+ * placement a match needs, so the work is O(value × pattern) at worst, never the
+ * exponential / polynomial backtracking a regex would do. The pattern length is capped
+ * at {@link MAX_PATTERN_LENGTH} (a `VALIDATION` {@link DatabaseError} over it), bounding
+ * the pattern factor so a match stays linear in the value length whatever the pattern.
  *
  * The `any` wildcard matches any run (including empty); `single` matches exactly one
- * char; every other pattern char matches itself literally (a pattern `.` / `(` / `\` is
- * a literal — the regex-metacharacter hazard is gone with the regex). `any` is tested
- * before a literal match, so a value that literally contains the wildcard char never
- * shadows the wildcard. Case folding is applied to both sides when `fold` is set.
+ * UTF-16 code unit; every other pattern char matches itself literally (a pattern `.` /
+ * `(` / `\` is a literal — the regex-metacharacter hazard is gone with the regex). The
+ * pattern splits on `any` before any literal comparison, so a value that literally
+ * contains the wildcard char never shadows the wildcard. Case folding is applied to
+ * both sides when `fold` is set.
  *
  * @param value - The value to test
  * @param pattern - The wildcard pattern
@@ -1146,6 +1162,26 @@ export declare function matchesQuery(row: Row, conditions: readonly Condition[])
  */
 export declare function matchesWildcardPattern(value: string, pattern: string, any: string, single: string, fold: boolean): boolean;
 
+/**
+ * Checks whether a fixed-length wildcard segment matches a value at an offset.
+ *
+ * @remarks
+ * Compares UTF-16 code units: `single` matches any one unit, and every other segment
+ * unit matches itself. An offset that leaves the segment outside the value fails.
+ *
+ * @param value - The value to read
+ * @param segment - The segment, holding no any-run wildcard
+ * @param at - The value offset the segment starts at
+ * @param single - The single-char wildcard char
+ * @returns True if every segment unit matches the value unit at its offset; false otherwise
+ *
+ * @example
+ * ```ts
+ * matchesWildcardSegment('hello', 'l_o', 2, '_') // true
+ * ```
+ */
+export declare function matchesWildcardSegment(value: string, segment: string, at: number, single: string): boolean;
+
 /**
  * Sets the longest `LIKE` / `GLOB` pattern the wildcard matcher accepts, 1024 characters, before
  * rejecting it.
@@ -1770,6 +1806,24 @@ export declare interface StorageInterface {
     stamp?(metadata: DriverMetadata): Promise<void>;
 }
 
+/**
+ * Tracks the matching-row position of one streaming page.
+ *
+ * @example
+ * ```ts
+ * const page = new StreamPage(1)
+ * page.next() // false
+ * page.next() // true
+ * page.count // 1
+ * ```
+ */
+export declare class StreamPage {
+    #private;
+    constructor(offset: number);
+    get count(): number;
+    next(): boolean;
+}
+
 /**
  * Represents one table's portable definition, produced by `export` — the unit of schema /
  * migration exchange across environments.

package/dist/src/core/index.d.ts

@@ -89,6 +89,16 @@ export declare function auditDriver(factory: () => DriverInterface): Promise<rea
  */
 export declare function bindRowKey(row: Row, primary: string, key: Key): Row;
 
+/**
+ * Captures the exact rejection or synchronous throw from a driver conformance operation.
+ *
+ * @example
+ * ```ts
+ * await captureFailure(() => Promise.reject('refused')) // 'refused'
+ * ```
+ */
+export declare function captureFailure(operation: () => Promise<unknown>): Promise<unknown>;
+
 /**
  * Throws when an {@link OperationOptions.signal | AbortSignal} has fired — the shared
  * abort gate checked at operation boundaries and between streamed rows.
@@ -913,6 +923,11 @@ export declare function isColumnSchema(value: unknown): value is ColumnSchema;
 /**
  * Narrows an unknown caught value to a {@link DatabaseError}.
  *
+ * @remarks
+ * Accepts branded instances and subclasses across package copies and module formats.
+ * Requires the declared code and context shape. Refuses look-alikes and transparent
+ * proxies without requiring an exact `name`.
+ *
  * @param value - The value to test (typically a `catch` binding)
  * @returns True if `value` is a {@link DatabaseError}; false otherwise
  *
@@ -1122,19 +1137,20 @@ export declare function matchesQuery(row: Row, conditions: readonly Condition[])
  * `.*` segments separated by literals, matched against a long non-matching input, blow
  * up super-linearly — and JS has no atomic groups / possessive quantifiers to bound it,
  * while a `LIKE` / `GLOB` pattern is a caller-supplied operand this package cannot
- * trust. So this builds no regex. It runs the classic greedy two-pointer wildcard match:
- * the `any` wildcard records its position and, on a later mismatch, backtracks only to
- * that last `any` (letting it absorb one more char) — so the work is O(value × pattern),
- * never the exponential / polynomial backtracking a regex would do. The pattern length
- * is capped at {@link MAX_PATTERN_LENGTH} (a `VALIDATION` {@link DatabaseError} over it),
- * bounding the pattern factor so a match stays linear in the value length whatever the
- * pattern.
+ * trust. This builds no regex. It splits the pattern on `any` into fixed-length
+ * segments, anchors the first at the value's start and the last at its end, and places
+ * each middle segment at its leftmost match after the one before it, which is the only
+ * placement a match needs, so the work is O(value × pattern) at worst, never the
+ * exponential / polynomial backtracking a regex would do. The pattern length is capped
+ * at {@link MAX_PATTERN_LENGTH} (a `VALIDATION` {@link DatabaseError} over it), bounding
+ * the pattern factor so a match stays linear in the value length whatever the pattern.
  *
  * The `any` wildcard matches any run (including empty); `single` matches exactly one
- * char; every other pattern char matches itself literally (a pattern `.` / `(` / `\` is
- * a literal — the regex-metacharacter hazard is gone with the regex). `any` is tested
- * before a literal match, so a value that literally contains the wildcard char never
- * shadows the wildcard. Case folding is applied to both sides when `fold` is set.
+ * UTF-16 code unit; every other pattern char matches itself literally (a pattern `.` /
+ * `(` / `\` is a literal — the regex-metacharacter hazard is gone with the regex). The
+ * pattern splits on `any` before any literal comparison, so a value that literally
+ * contains the wildcard char never shadows the wildcard. Case folding is applied to
+ * both sides when `fold` is set.
  *
  * @param value - The value to test
  * @param pattern - The wildcard pattern
@@ -1146,6 +1162,26 @@ export declare function matchesQuery(row: Row, conditions: readonly Condition[])
  */
 export declare function matchesWildcardPattern(value: string, pattern: string, any: string, single: string, fold: boolean): boolean;
 
+/**
+ * Checks whether a fixed-length wildcard segment matches a value at an offset.
+ *
+ * @remarks
+ * Compares UTF-16 code units: `single` matches any one unit, and every other segment
+ * unit matches itself. An offset that leaves the segment outside the value fails.
+ *
+ * @param value - The value to read
+ * @param segment - The segment, holding no any-run wildcard
+ * @param at - The value offset the segment starts at
+ * @param single - The single-char wildcard char
+ * @returns True if every segment unit matches the value unit at its offset; false otherwise
+ *
+ * @example
+ * ```ts
+ * matchesWildcardSegment('hello', 'l_o', 2, '_') // true
+ * ```
+ */
+export declare function matchesWildcardSegment(value: string, segment: string, at: number, single: string): boolean;
+
 /**
  * Sets the longest `LIKE` / `GLOB` pattern the wildcard matcher accepts, 1024 characters, before
  * rejecting it.
@@ -1770,6 +1806,24 @@ export declare interface StorageInterface {
     stamp?(metadata: DriverMetadata): Promise<void>;
 }
 
+/**
+ * Tracks the matching-row position of one streaming page.
+ *
+ * @example
+ * ```ts
+ * const page = new StreamPage(1)
+ * page.next() // false
+ * page.next() // true
+ * page.count // 1
+ * ```
+ */
+export declare class StreamPage {
+    #private;
+    constructor(offset: number);
+    get count(): number;
+    next(): boolean;
+}
+
 /**
  * Represents one table's portable definition, produced by `export` — the unit of schema /
  * migration exchange across environments.