@honua/react 0.1.12 → 0.1.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. package/columnar/apache-arrow.d.ts +17 -0
  2. package/columnar/apache-arrow.d.ts.map +1 -0
  3. package/columnar/apache-arrow.js +1036 -0
  4. package/columnar/batch-cache-conformance.d.ts +66 -0
  5. package/columnar/batch-cache-conformance.d.ts.map +1 -0
  6. package/columnar/batch-cache-conformance.js +317 -0
  7. package/columnar/batch-cache-indexeddb.d.ts +31 -0
  8. package/columnar/batch-cache-indexeddb.d.ts.map +1 -0
  9. package/columnar/batch-cache-indexeddb.js +148 -0
  10. package/columnar/batch-cache.d.ts +298 -0
  11. package/columnar/batch-cache.d.ts.map +1 -0
  12. package/columnar/batch-cache.js +757 -0
  13. package/columnar/geoarrow-aggregate.d.ts +178 -0
  14. package/columnar/geoarrow-aggregate.d.ts.map +1 -0
  15. package/columnar/geoarrow-aggregate.js +976 -0
  16. package/columnar/geoarrow-patch.d.ts +382 -0
  17. package/columnar/geoarrow-patch.d.ts.map +1 -0
  18. package/columnar/geoarrow-patch.js +1656 -0
  19. package/columnar/geoarrow-reproject.d.ts +22 -0
  20. package/columnar/geoarrow-reproject.d.ts.map +1 -0
  21. package/columnar/geoarrow-reproject.js +119 -0
  22. package/columnar/geoarrow-serialization.d.ts +68 -0
  23. package/columnar/geoarrow-serialization.d.ts.map +1 -0
  24. package/columnar/geoarrow-serialization.js +331 -0
  25. package/columnar/geoarrow-types.d.ts +271 -0
  26. package/columnar/geoarrow-types.d.ts.map +1 -0
  27. package/columnar/geoarrow-types.js +15 -0
  28. package/columnar/geoarrow.d.ts +52 -0
  29. package/columnar/geoarrow.d.ts.map +1 -0
  30. package/columnar/geoarrow.js +1469 -0
  31. package/columnar/index.d.ts +43 -0
  32. package/columnar/index.d.ts.map +1 -0
  33. package/columnar/index.js +29 -0
  34. package/columnar/operators.d.ts +70 -0
  35. package/columnar/operators.d.ts.map +1 -0
  36. package/columnar/operators.js +307 -0
  37. package/columnar/result.d.ts +369 -0
  38. package/columnar/result.d.ts.map +1 -0
  39. package/columnar/result.js +815 -0
  40. package/columnar/telemetry.d.ts +152 -0
  41. package/columnar/telemetry.d.ts.map +1 -0
  42. package/columnar/telemetry.js +265 -0
  43. package/columnar/transfer.d.ts +28 -0
  44. package/columnar/transfer.d.ts.map +1 -0
  45. package/columnar/transfer.js +669 -0
  46. package/columnar/types.d.ts +175 -0
  47. package/columnar/types.d.ts.map +1 -0
  48. package/columnar/types.js +22 -0
  49. package/columnar/worker.d.ts +157 -0
  50. package/columnar/worker.d.ts.map +1 -0
  51. package/columnar/worker.js +1059 -0
  52. package/connect-url-safety.d.ts +53 -0
  53. package/connect-url-safety.js +189 -0
  54. package/contract/pmtiles.d.ts +6 -5
  55. package/contract/pmtiles.d.ts.map +1 -1
  56. package/contract/pmtiles.js +30 -5
  57. package/contract/source.d.ts.map +1 -1
  58. package/contract/source.js +11 -8
  59. package/core/client.d.ts.map +1 -1
  60. package/core/client.js +87 -19
  61. package/core/deprecation-notice.d.ts +28 -0
  62. package/core/deprecation-notice.d.ts.map +1 -0
  63. package/core/deprecation-notice.js +22 -0
  64. package/core/esri-geojson.d.ts.map +1 -1
  65. package/core/esri-geojson.js +14 -8
  66. package/core/optional-grpc-peer.d.ts +15 -0
  67. package/core/optional-grpc-peer.d.ts.map +1 -0
  68. package/core/optional-grpc-peer.js +60 -0
  69. package/esri-compat/basemap-gallery.d.ts +2 -0
  70. package/esri-compat/basemap-gallery.d.ts.map +1 -1
  71. package/esri-compat/basemap-gallery.js +12 -0
  72. package/esri-compat/basemap.d.ts +4 -0
  73. package/esri-compat/basemap.d.ts.map +1 -1
  74. package/esri-compat/basemap.js +70 -0
  75. package/esri-compat/bookmarks.d.ts +2 -0
  76. package/esri-compat/bookmarks.d.ts.map +1 -1
  77. package/esri-compat/bookmarks.js +12 -0
  78. package/esri-compat/controls.d.ts +18 -0
  79. package/esri-compat/controls.d.ts.map +1 -1
  80. package/esri-compat/controls.js +120 -57
  81. package/esri-compat/directions.d.ts +4 -0
  82. package/esri-compat/directions.d.ts.map +1 -1
  83. package/esri-compat/directions.js +30 -20
  84. package/esri-compat/editor.d.ts +4 -0
  85. package/esri-compat/editor.d.ts.map +1 -1
  86. package/esri-compat/editor.js +16 -0
  87. package/esri-compat/esri-config.d.ts +2 -1
  88. package/esri-compat/esri-config.d.ts.map +1 -1
  89. package/esri-compat/feature-effect.d.ts +23 -0
  90. package/esri-compat/feature-effect.d.ts.map +1 -0
  91. package/esri-compat/feature-effect.js +12 -0
  92. package/esri-compat/feature-form.d.ts +6 -0
  93. package/esri-compat/feature-form.d.ts.map +1 -1
  94. package/esri-compat/feature-form.js +63 -0
  95. package/esri-compat/feature-layer.d.ts +21 -2
  96. package/esri-compat/feature-layer.d.ts.map +1 -1
  97. package/esri-compat/feature-layer.js +172 -1
  98. package/esri-compat/feature-table.d.ts +5 -0
  99. package/esri-compat/feature-table.d.ts.map +1 -1
  100. package/esri-compat/feature-table.js +23 -0
  101. package/esri-compat/identity-manager.d.ts +1 -1
  102. package/esri-compat/identity-manager.js +1 -1
  103. package/esri-compat/legend.d.ts +2 -0
  104. package/esri-compat/legend.d.ts.map +1 -1
  105. package/esri-compat/legend.js +98 -0
  106. package/esri-compat/locator.d.ts +1 -1
  107. package/esri-compat/locator.js +1 -1
  108. package/esri-compat/map-view-mount.d.ts +1 -0
  109. package/esri-compat/map-view-mount.d.ts.map +1 -1
  110. package/esri-compat/map-view-mount.js +46 -25
  111. package/esri-compat/map-view.d.ts +13 -0
  112. package/esri-compat/map-view.d.ts.map +1 -1
  113. package/esri-compat/map-view.js +94 -8
  114. package/esri-compat/map.d.ts +5 -1
  115. package/esri-compat/map.d.ts.map +1 -1
  116. package/esri-compat/map.js +10 -0
  117. package/esri-compat/measurement.d.ts +2 -0
  118. package/esri-compat/measurement.d.ts.map +1 -1
  119. package/esri-compat/measurement.js +14 -0
  120. package/esri-compat/point.d.ts +7 -0
  121. package/esri-compat/point.d.ts.map +1 -1
  122. package/esri-compat/point.js +33 -3
  123. package/esri-compat/popup.d.ts +2 -0
  124. package/esri-compat/popup.d.ts.map +1 -1
  125. package/esri-compat/popup.js +12 -0
  126. package/esri-compat/portal.d.ts +1 -1
  127. package/esri-compat/portal.js +1 -1
  128. package/esri-compat/print.d.ts +3 -0
  129. package/esri-compat/print.d.ts.map +1 -1
  130. package/esri-compat/print.js +15 -0
  131. package/esri-compat/search.d.ts +4 -0
  132. package/esri-compat/search.d.ts.map +1 -1
  133. package/esri-compat/search.js +25 -28
  134. package/esri-compat/sketch.d.ts +2 -0
  135. package/esri-compat/sketch.d.ts.map +1 -1
  136. package/esri-compat/sketch.js +12 -0
  137. package/esri-compat/widget-host.d.ts +46 -17
  138. package/esri-compat/widget-host.d.ts.map +1 -1
  139. package/esri-compat/widget-host.js +84 -20
  140. package/esri-compat/widget-shell-hosts.d.ts +61 -0
  141. package/esri-compat/widget-shell-hosts.d.ts.map +1 -0
  142. package/esri-compat/widget-shell-hosts.js +76 -0
  143. package/geocoding/index.d.ts +114 -0
  144. package/geocoding/index.d.ts.map +1 -0
  145. package/geocoding/index.js +293 -0
  146. package/geocoding/provider-http.d.ts +37 -0
  147. package/geocoding/provider-http.d.ts.map +1 -0
  148. package/geocoding/provider-http.js +93 -0
  149. package/geocoding/provider.d.ts +145 -0
  150. package/geocoding/provider.d.ts.map +1 -0
  151. package/geocoding/provider.js +41 -0
  152. package/geocoding/providers/honua.d.ts +28 -0
  153. package/geocoding/providers/honua.d.ts.map +1 -0
  154. package/geocoding/providers/honua.js +68 -0
  155. package/geocoding/providers/nominatim.d.ts +47 -0
  156. package/geocoding/providers/nominatim.d.ts.map +1 -0
  157. package/geocoding/providers/nominatim.js +105 -0
  158. package/geocoding/providers/pelias.d.ts +40 -0
  159. package/geocoding/providers/pelias.d.ts.map +1 -0
  160. package/geocoding/providers/pelias.js +115 -0
  161. package/geocoding/providers/photon.d.ts +39 -0
  162. package/geocoding/providers/photon.d.ts.map +1 -0
  163. package/geocoding/providers/photon.js +107 -0
  164. package/geometry/convert.d.ts +13 -0
  165. package/geometry/convert.d.ts.map +1 -0
  166. package/geometry/convert.js +12 -0
  167. package/geometry/index.d.ts +17 -0
  168. package/geometry/index.d.ts.map +1 -0
  169. package/geometry/index.js +15 -0
  170. package/geometry/internal.d.ts +25 -0
  171. package/geometry/internal.d.ts.map +1 -0
  172. package/geometry/internal.js +40 -0
  173. package/geometry/ops.d.ts +71 -0
  174. package/geometry/ops.d.ts.map +1 -0
  175. package/geometry/ops.js +147 -0
  176. package/geometry/project.d.ts +40 -0
  177. package/geometry/project.d.ts.map +1 -0
  178. package/geometry/project.js +88 -0
  179. package/geometry/types.d.ts +36 -0
  180. package/geometry/types.d.ts.map +1 -0
  181. package/geometry/types.js +12 -0
  182. package/kernel/renderer.d.ts +82 -0
  183. package/kernel/renderer.js +1 -0
  184. package/offline/digest.d.ts +15 -0
  185. package/offline/digest.js +58 -0
  186. package/offline/quota.d.ts +161 -0
  187. package/offline/quota.js +370 -0
  188. package/offline/types.d.ts +349 -0
  189. package/offline/types.js +75 -0
  190. package/package.json +14 -2
  191. package/realtime/odata-delta.d.ts +1 -1
  192. package/realtime/odata-delta.d.ts.map +1 -1
  193. package/realtime/odata-delta.js +38 -10
  194. package/widget-capabilities.d.ts +67 -0
  195. package/widget-capabilities.js +152 -0
@@ -0,0 +1,369 @@
1
+ /**
2
+ * Bounded conversion between Honua columnar batches and the protocol-neutral
3
+ * object `Result` contract.
4
+ *
5
+ * The columnar plane is deliberately one-way at the buffer level: rows go in,
6
+ * GPU-ready binaries come out, and nothing per-feature is ever materialized.
7
+ * That is what keeps a million-row batch affordable, but it also means the
8
+ * first time an application needs a popup, a table page, an export, or an
9
+ * assertion in the shape the rest of the SDK speaks, it has no way back. These
10
+ * two functions are that way back, and they are bounded by construction.
11
+ *
12
+ * **The ceiling is the feature, not a guard rail.** Materializing feature
13
+ * objects costs roughly two orders of magnitude more memory per row than the
14
+ * packed columns they came from, so an unbounded conversion is exactly the
15
+ * silent materialization the columnar plane exists to avoid. `maxFeatures` is
16
+ * therefore a required option on both directions, it is enforced before a
17
+ * single feature object is allocated, and there is no sentinel, no `Infinity`,
18
+ * and no options object that disables it. A conversion that would exceed it
19
+ * fails closed with `HonuaGeoArrowError` code `row-limit-exceeded` naming both
20
+ * the ceiling and the requested count.
21
+ *
22
+ * Conversion reads only the requested window. Payload validation that the
23
+ * unbounded {@link inspectGeoArrowBatch} performs over the whole batch is
24
+ * performed here per materialized row instead, so cost stays proportional to
25
+ * the window rather than to the batch.
26
+ *
27
+ * **Loss is reported, never taken silently.** The forward direction is complete
28
+ * by construction: a normative GeoArrow batch carries exactly a geometry column
29
+ * plus optional temporal, dictionary, and feature-id columns, and every one of
30
+ * them lands on the converted feature. The inverse direction is where an object
31
+ * `Result` can carry more than a columnar batch can hold, so it fails closed on
32
+ * an attribute no column binding covers rather than dropping it, and the only
33
+ * way to proceed is an explicit opt-in that names every dropped attribute back
34
+ * to the caller.
35
+ *
36
+ * **Traversing more than one window is streaming, not a bigger window.**
37
+ * {@link columnarBatchToResultPages} walks a batch as a sequence of bounded
38
+ * pages, holding one page at a time, checking a caller's `AbortSignal` on a row
39
+ * cadence, and yielding to the host task queue between pages so a cancellation
40
+ * can actually land. The ceiling still applies — to each page.
41
+ *
42
+ * @experimental
43
+ */
44
+ import type { Result } from "../contract/types.js";
45
+ import type { ColumnarBatchIdentityV1, CreatedGeoArrowBatch, GeoArrowConversionLimits, GeoArrowCoordinateLayout, GeoArrowCrs, GeoArrowDimensions, GeoArrowEdges, GeoArrowGeometryKind, GeoArrowLineString, GeoArrowPoint, GeoArrowPolygon, GeoArrowTimestampUnit } from "./geoarrow-types.js";
46
+ import { type ColumnarTelemetryOptions } from "./telemetry.js";
47
+ import type { ColumnarBatchV1 } from "./types.js";
48
+ /**
49
+ * Conservative ceiling recommended for a bounded conversion window.
50
+ *
51
+ * It exists because feature objects, unlike the packed columns they are read
52
+ * from, cost hundreds of bytes per row: a hundred thousand point features is
53
+ * already tens of megabytes of live JavaScript objects, which is the largest
54
+ * bounded window that still behaves like an interaction rather than a bulk
55
+ * export. It is exported as a documented starting point, **not** applied
56
+ * implicitly — `maxFeatures` is always explicit at the call site so the cost of
57
+ * materialization is always visible in the calling code.
58
+ */
59
+ export declare const DEFAULT_COLUMNAR_RESULT_MAX_FEATURES = 100000;
60
+ /** GeoJSON geometry types the Honua columnar geometry kinds map onto. */
61
+ export type ColumnarGeoJsonGeometryType = "Point" | "LineString" | "Polygon";
62
+ /**
63
+ * GeoJSON geometry emitted onto a converted feature.
64
+ *
65
+ * Positions carry two components for `xy` and three for `xyz` geometry, in
66
+ * `[x, y]` / `[x, y, z]` order. `xym` and `xyzm` batches are rejected rather
67
+ * than silently stripped, because GeoJSON has no representation for an M
68
+ * coordinate and dropping it would be a lossy conversion presented as a
69
+ * successful one.
70
+ */
71
+ export type ColumnarGeoJsonGeometry = {
72
+ readonly type: ColumnarGeoJsonGeometryType;
73
+ readonly coordinates: GeoArrowPoint | GeoArrowLineString | GeoArrowPolygon;
74
+ };
75
+ /** Attribute a batch's non-nullable `uint32` feature-id column is emitted as. */
76
+ export interface ColumnarResultFeatureIdBinding {
77
+ readonly attribute: string;
78
+ }
79
+ /**
80
+ * Attribute a batch's timestamp column is emitted as.
81
+ *
82
+ * The attribute value is the Arrow timestamp as a `bigint` in `unit`, never a
83
+ * `Date` and never epoch milliseconds, so microsecond and nanosecond batches
84
+ * round-trip exactly. A null timestamp becomes an explicit `null` attribute.
85
+ */
86
+ export interface ColumnarResultTemporalBinding {
87
+ readonly attribute: string;
88
+ readonly unit: GeoArrowTimestampUnit;
89
+ readonly timezone?: string;
90
+ }
91
+ /**
92
+ * Attribute a batch's dictionary-encoded UTF-8 column is emitted as.
93
+ *
94
+ * Dictionary encoding is a storage detail: the attribute carries the decoded
95
+ * `string`, and a null dictionary value becomes an explicit `null` attribute
96
+ * rather than an omitted key or the zero-index value.
97
+ */
98
+ export interface ColumnarResultDictionaryBinding {
99
+ readonly attribute: string;
100
+ readonly ordered: boolean;
101
+ }
102
+ /** Declared attribute names every converted feature carries. */
103
+ export interface ColumnarResultAttributeBinding {
104
+ readonly featureId?: ColumnarResultFeatureIdBinding;
105
+ readonly temporal?: ColumnarResultTemporalBinding;
106
+ readonly dictionary?: ColumnarResultDictionaryBinding;
107
+ }
108
+ /** Geometry layout of the column a bounded `Result` was converted from. */
109
+ export interface ColumnarResultGeometryDescriptor {
110
+ readonly kind: GeoArrowGeometryKind;
111
+ readonly field: string;
112
+ readonly dimensions: GeoArrowDimensions;
113
+ readonly coordinateLayout: GeoArrowCoordinateLayout;
114
+ readonly edges: GeoArrowEdges;
115
+ }
116
+ /**
117
+ * Everything a bounded object view must carry to stay honest about the batch
118
+ * it came from, and everything {@link resultToColumnarBatch} needs to put it
119
+ * back without the caller restating the layout.
120
+ *
121
+ * `identity` is the source batch's own cache, authorization, ordering, and
122
+ * freshness identity, copied and never re-observed: a bounded object view can
123
+ * therefore never look fresher, differently ordered, or differently scoped
124
+ * than the batch it was cut from.
125
+ */
126
+ export interface ColumnarResultProvenance {
127
+ readonly batchId: string;
128
+ readonly schemaId: string;
129
+ readonly sequence: number;
130
+ /** Rows in the source batch, which is not the number of converted features. */
131
+ readonly batchRowCount: number;
132
+ /** Zero-based index of the first converted row within the source batch. */
133
+ readonly offset: number;
134
+ /** Converted feature count. Never greater than `maxFeatures`. */
135
+ readonly count: number;
136
+ /** Absolute row offset of the first converted row in the logical row stream. */
137
+ readonly rowOffset: number;
138
+ /** Ceiling that bounded this conversion. */
139
+ readonly maxFeatures: number;
140
+ readonly geometry: ColumnarResultGeometryDescriptor;
141
+ readonly attributes: ColumnarResultAttributeBinding;
142
+ readonly identity: ColumnarBatchIdentityV1;
143
+ }
144
+ /**
145
+ * A protocol-neutral {@link Result} produced from a bounded columnar window.
146
+ *
147
+ * It **is** a `Result`: every consumer that accepts an object-path result
148
+ * accepts this unchanged. The two extra members exist because the shared
149
+ * envelope has nowhere to put them — `crs` so a consumer is never left
150
+ * assuming EPSG:4326, and `columnar` so the bounded view carries the batch's
151
+ * ordering and freshness with it.
152
+ */
153
+ export interface ColumnarResult<T = Record<string, unknown>> extends Result<T> {
154
+ /**
155
+ * CRS the batch declared for its geometry column: a serialized CRS string or
156
+ * a PROJJSON object. Undefined when the batch declared none, in which case
157
+ * the coordinates carry no CRS claim at all and a consumer must not invent
158
+ * one.
159
+ */
160
+ readonly crs?: GeoArrowCrs;
161
+ /** Provenance of the bounded window this `Result` was cut from. */
162
+ readonly columnar: ColumnarResultProvenance;
163
+ }
164
+ /** Explicit conversion window. There is no unbounded mode. */
165
+ export interface ColumnarBatchToResultOptions extends ColumnarTelemetryOptions {
166
+ /**
167
+ * Hard ceiling on converted features. Required: conversion refuses rather
168
+ * than materializing an unbounded number of feature objects.
169
+ */
170
+ readonly maxFeatures: number;
171
+ /** Zero-based first row of the window. Defaults to the start of the batch. */
172
+ readonly offset?: number;
173
+ /** Rows to convert from `offset`. Defaults to the rest of the batch. */
174
+ readonly limit?: number;
175
+ /** Structural limits forwarded to batch inspection. */
176
+ readonly limits?: GeoArrowConversionLimits;
177
+ }
178
+ /**
179
+ * Explicit page shape for {@link columnarBatchToResultPages}.
180
+ *
181
+ * The ceiling bounds each page rather than the traversal: a caller streaming a
182
+ * million-row batch holds one page at a time, so the retained cost is the page,
183
+ * not the batch. `limit` bounds how much of the batch is walked at all.
184
+ */
185
+ export interface ColumnarBatchToResultPagesOptions extends ColumnarTelemetryOptions {
186
+ /**
187
+ * Hard ceiling on the features one page may carry. Required, and `pageSize`
188
+ * may not exceed it.
189
+ */
190
+ readonly maxFeatures: number;
191
+ /** Rows per page. Defaults to `maxFeatures`. The final page may be shorter. */
192
+ readonly pageSize?: number;
193
+ /** Zero-based first row of the traversal. Defaults to the start of the batch. */
194
+ readonly offset?: number;
195
+ /** Rows to walk from `offset`. Defaults to the rest of the batch. */
196
+ readonly limit?: number;
197
+ /**
198
+ * Cooperative cancellation. Checked before each page and every 1,024 rows
199
+ * within a page; the traversal yields to the host task queue between pages so
200
+ * an abort raised by a task — a worker message, a timer, a user gesture — is
201
+ * actually delivered rather than starved by an uninterrupted loop.
202
+ */
203
+ readonly signal?: AbortSignal;
204
+ /** Structural limits forwarded to batch inspection, performed once. */
205
+ readonly limits?: GeoArrowConversionLimits;
206
+ }
207
+ /** Geometry layout for {@link resultToColumnarBatch}. */
208
+ export interface ResultToColumnarBatchGeometryOptions {
209
+ readonly field?: string;
210
+ readonly kind?: GeoArrowGeometryKind;
211
+ readonly dimensions?: GeoArrowDimensions;
212
+ readonly coordinateLayout?: GeoArrowCoordinateLayout;
213
+ readonly edges?: GeoArrowEdges;
214
+ readonly crs?: GeoArrowCrs;
215
+ }
216
+ /** Attributes {@link resultToColumnarBatch} lifts into typed columns. */
217
+ export interface ResultToColumnarBatchAttributeOptions {
218
+ readonly featureId?: ColumnarResultFeatureIdBinding;
219
+ readonly temporal?: ColumnarResultTemporalBinding;
220
+ readonly dictionary?: {
221
+ readonly attribute: string;
222
+ readonly ordered?: boolean;
223
+ };
224
+ }
225
+ /**
226
+ * Explicit conversion window plus the batch identity an object-path `Result`
227
+ * cannot supply on its own. Every field except `maxFeatures` defaults from
228
+ * {@link ColumnarResult.columnar} when the `Result` came from
229
+ * {@link columnarBatchToResult}.
230
+ */
231
+ export interface ResultToColumnarBatchOptions {
232
+ /**
233
+ * Hard ceiling on converted rows. Required, for the same reason as on
234
+ * {@link ColumnarBatchToResultOptions}.
235
+ */
236
+ readonly maxFeatures: number;
237
+ /** Zero-based first feature of the window. Defaults to the first feature. */
238
+ readonly offset?: number;
239
+ /** Features to convert from `offset`. Defaults to the rest of the array. */
240
+ readonly limit?: number;
241
+ readonly id?: string;
242
+ readonly sequence?: number;
243
+ readonly rowOffset?: number;
244
+ readonly schemaId?: string;
245
+ readonly identity?: ColumnarBatchIdentityV1;
246
+ readonly geometry?: ResultToColumnarBatchGeometryOptions;
247
+ readonly attributes?: ResultToColumnarBatchAttributeOptions;
248
+ readonly limits?: GeoArrowConversionLimits;
249
+ /**
250
+ * What to do with an attribute no column binding covers.
251
+ *
252
+ * A normative GeoArrow batch holds exactly a geometry column plus optional
253
+ * temporal, dictionary, and feature-id columns, so an object `Result` can
254
+ * always carry attributes the batch cannot. `"fail"` — the default — refuses
255
+ * with `unsupported-layout` naming the attribute, because dropping a value
256
+ * the caller did not agree to lose is exactly the silent coercion this module
257
+ * exists to prevent. `"drop"` is the explicit opt-in, and even then every
258
+ * dropped attribute name is reported back on
259
+ * {@link ResultToColumnarBatchResult.droppedAttributes} so the loss is stated
260
+ * rather than assumed.
261
+ */
262
+ readonly unmappedAttributes?: "fail" | "drop";
263
+ }
264
+ /**
265
+ * A created batch plus the explicit statement of what did not fit in it.
266
+ *
267
+ * `droppedAttributes` is empty for every conversion that did not opt in to
268
+ * dropping, which is the default, so a caller that never sets
269
+ * `unmappedAttributes` can treat a returned result as lossless without checking.
270
+ */
271
+ export interface ResultToColumnarBatchResult extends CreatedGeoArrowBatch {
272
+ /**
273
+ * Attribute names present on the converted features that no column binding
274
+ * carried into the batch, sorted and deduplicated so the report is
275
+ * deterministic. Always empty unless `unmappedAttributes: "drop"` was set.
276
+ */
277
+ readonly droppedAttributes: readonly string[];
278
+ }
279
+ /**
280
+ * Convert a bounded, contiguous row window of a columnar batch into a
281
+ * protocol-neutral {@link Result} of typed features.
282
+ *
283
+ * Features are emitted in batch row order, so the `Result` preserves the
284
+ * batch's declared ordering exactly. Geometry becomes GeoJSON, the batch's
285
+ * feature-id, timestamp, and dictionary columns become attributes under their
286
+ * declared names, and a null timestamp or dictionary value becomes an explicit
287
+ * `null` attribute rather than a missing key.
288
+ *
289
+ * This direction is complete: a normative GeoArrow batch carries exactly those
290
+ * four columns, so nothing on the batch is left behind and there is no loss to
291
+ * report. Use {@link columnarBatchToResultPages} to walk more of a batch than
292
+ * one window without raising the ceiling.
293
+ *
294
+ * @throws HonuaGeoArrowError `row-limit-exceeded` when the window exceeds
295
+ * `options.maxFeatures`. The ceiling is checked before the batch is inspected,
296
+ * so nothing is read or allocated on that path.
297
+ * @throws HonuaGeoArrowError `unsupported-layout` for `xym`/`xyzm` geometry,
298
+ * which GeoJSON cannot represent.
299
+ *
300
+ * @example
301
+ * ```ts
302
+ * const result = columnarBatchToResult(batch, { offset: 0, limit: 50, maxFeatures: 200 });
303
+ * for (const feature of result.features) console.log(feature.geometry, feature.attributes);
304
+ * ```
305
+ */
306
+ export declare function columnarBatchToResult<T extends Record<string, unknown> = Record<string, unknown>>(batch: ColumnarBatchV1, options: ColumnarBatchToResultOptions): ColumnarResult<T>;
307
+ /**
308
+ * Walk a batch as a sequence of bounded {@link ColumnarResult} pages.
309
+ *
310
+ * This is how a caller converts more of a batch than one window without raising
311
+ * the ceiling: each page is a complete, independently valid `Result` bounded by
312
+ * `maxFeatures`, and only the page a consumer is holding is live. A consumer
313
+ * that streams a million-row batch to a file therefore retains one page, not a
314
+ * million features.
315
+ *
316
+ * Pages are emitted in ascending row order, contiguous and non-overlapping, so
317
+ * concatenating every page's `features` reproduces exactly the feature sequence
318
+ * a single window over the same range would have produced. An empty range
319
+ * yields no pages at all rather than one empty page.
320
+ *
321
+ * Cancellation is cooperative and real: `options.signal` is checked before each
322
+ * page and every 1,024 rows inside a page, and the traversal yields to the host
323
+ * task queue between pages so an abort raised by a task is actually delivered.
324
+ * An aborted traversal rejects with an `AbortError` `DOMException` and stops
325
+ * without materializing the remaining pages.
326
+ *
327
+ * @throws HonuaGeoArrowError `invalid-input` when `pageSize` is not a positive
328
+ * safe integer, and `row-limit-exceeded` when `pageSize` exceeds `maxFeatures`.
329
+ * Both are checked before the batch is inspected.
330
+ *
331
+ * @example
332
+ * ```ts
333
+ * for await (const page of columnarBatchToResultPages(batch, { pageSize: 1_000, maxFeatures: 1_000, signal })) {
334
+ * await writeRows(page.features);
335
+ * }
336
+ * ```
337
+ */
338
+ export declare function columnarBatchToResultPages<T extends Record<string, unknown> = Record<string, unknown>>(batch: ColumnarBatchV1, options: ColumnarBatchToResultPagesOptions): AsyncGenerator<ColumnarResult<T>, void, undefined>;
339
+ /**
340
+ * Convert a bounded, contiguous window of an object-path {@link Result} into a
341
+ * normative GeoArrow columnar batch.
342
+ *
343
+ * This is the inverse of {@link columnarBatchToResult} and is bounded the same
344
+ * way: `maxFeatures` is required and enforced before any feature is read. A
345
+ * `Result` produced by {@link columnarBatchToResult} carries enough provenance
346
+ * to default the batch identity, geometry layout, and attribute bindings; a
347
+ * plain object-path `Result` must supply `id`, `schemaId`, and `identity`, and
348
+ * any attribute it wants lifted into a typed column.
349
+ *
350
+ * Null and missing attributes are treated identically for the nullable
351
+ * timestamp and dictionary columns and become null column values. A feature-id
352
+ * column is not nullable, so a missing or null id fails closed.
353
+ *
354
+ * Unlike the forward direction this one can be asked to lose something: a
355
+ * columnar batch has four column roles and an object `Result` may carry any
356
+ * number of attributes. An attribute no binding covers therefore fails closed
357
+ * by default, and `unmappedAttributes: "drop"` is the only way past it —
358
+ * reporting every dropped name on
359
+ * {@link ResultToColumnarBatchResult.droppedAttributes} so the loss is stated
360
+ * rather than assumed.
361
+ *
362
+ * @throws HonuaGeoArrowError `row-limit-exceeded` when the window exceeds
363
+ * `options.maxFeatures`, checked before any feature is read.
364
+ * @throws HonuaGeoArrowError `unsupported-layout` when the window mixes
365
+ * geometry kinds, which a single columnar geometry column cannot carry, or
366
+ * carries an attribute no column binding covers.
367
+ */
368
+ export declare function resultToColumnarBatch<T extends Record<string, unknown> = Record<string, unknown>>(result: Result<T>, options: ResultToColumnarBatchOptions): ResultToColumnarBatchResult;
369
+ //# sourceMappingURL=result.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/columnar/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,KAAK,EACV,uBAAuB,EAEvB,oBAAoB,EAEpB,wBAAwB,EACxB,wBAAwB,EACxB,WAAW,EAEX,kBAAkB,EAClB,aAAa,EAEb,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,eAAe,EAEf,qBAAqB,EAEtB,MAAM,qBAAqB,CAAC;AAQ7B,OAAO,EAAE,KAAK,wBAAwB,EAAqB,MAAM,gBAAgB,CAAC;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oCAAoC,SAAU,CAAC;AAuB5D,yEAAyE;AACzE,MAAM,MAAM,2BAA2B,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,CAAC;AAE7E;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,aAAa,GAAG,kBAAkB,GAAG,eAAe,CAAC;CAC5E,CAAC;AAEF,iFAAiF;AACjF,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,gEAAgE;AAChE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,8BAA8B,CAAC;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,6BAA6B,CAAC;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,+BAA+B,CAAC;CACvD;AAED,2EAA2E;AAC3E,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,wBAAwB,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,gCAAgC,CAAC;IACpD,QAAQ,CAAC,UAAU,EAAE,8BAA8B,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,MAAM,CAAC,CAAC,CAAC;IAC5E;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;CAC7C;AAED,8DAA8D;AAC9D,MAAM,WAAW,4BAA6B,SAAQ,wBAAwB;IAC5E;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iCAAkC,SAAQ,wBAAwB;IACjF;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;CAC5C;AAED,yDAAyD;AACzD,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,wBAAwB,CAAC;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC;CAC5B;AAED,yEAAyE;AACzE,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,8BAA8B,CAAC;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,6BAA6B,CAAC;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAClF;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,oCAAoC,CAAC;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,qCAAqC,CAAC;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAC3C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,2BAA4B,SAAQ,oBAAoB;IACvE;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C;AAubD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/F,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,4BAA4B,GACpC,cAAc,CAAC,CAAC,CAAC,CAmBnB;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAuB,0BAA0B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3G,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,iCAAiC,GACzC,cAAc,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAuDpD;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/F,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,4BAA4B,GACpC,2BAA2B,CA8N7B"}