Skip to content

Commit a29bd9c

Browse files
Sam-BollingSam-Bolling
committed
docs(csapi): correct public usage examples (#194)
1 parent 82db210 commit a29bd9c

6 files changed

Lines changed: 51 additions & 31 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ node examples/stac-query.js
129129

130130
The library includes support for the [OGC API — Connected Systems](https://ogcapi.ogc.org/connectedsystems/) standard ([Part 1: Feature Resources](https://docs.ogc.org/is/23-001/23-001.html), [Part 2: Dynamic Data](https://docs.ogc.org/is/23-002/23-002.html)). This standard extends the OGC API family into the IoT/sensor domain, providing a REST API for discovering and querying sensor systems, deployments, datastreams, observations, commands, and related resources.
131131

132-
CSAPI is available as an **opt-in sub-path export**, meaning it is only included in your production bundle if you explicitly import it.
132+
CSAPI remains behind an **opt-in module boundary**. The preferred `endpoint.csapi(...)` facade loads it dynamically when needed; parsers and the advanced factory are also available from the `@camptocamp/ogc-client/csapi` sub-path.
133133

134134
### If you don't need Connected Systems
135135

@@ -139,27 +139,44 @@ Nothing changes. Use the library exactly as before:
139139
import { OgcApiEndpoint, WmsEndpoint } from '@camptocamp/ogc-client';
140140
```
141141

142-
CSAPI code will not be included in your bundle.
142+
CSAPI code will not be loaded at runtime.
143143

144144
### If you need Connected Systems
145145

146-
Add a second import from the CSAPI sub-path:
146+
Use the discoverable endpoint facade:
147147

148148
```ts
149149
import { OgcApiEndpoint } from '@camptocamp/ogc-client';
150-
import { createCSAPIBuilder } from '@camptocamp/ogc-client/csapi';
151150

152151
const endpoint = new OgcApiEndpoint('https://api.example.org');
153152

154153
if (await endpoint.hasConnectedSystems) {
155-
const builder = await createCSAPIBuilder(endpoint, 'weather-stations');
154+
const builder = await endpoint.csapi('weather-stations');
156155
const systemsUrl = builder.getSystems({ limit: 50 });
157-
const dsUrl = builder.getDataStreams();
156+
const datastreamsUrl = builder.getDatastreams();
158157
}
159158
```
160159

161-
The `createCSAPIBuilder()` factory function connects to the endpoint and discovers available CSAPI resources. The returned `CSAPIQueryBuilder` provides methods for all 9 resource types: systems, deployments, sampling features, procedures, properties, datastreams, observations, control streams, and commands.
160+
The returned `CSAPIQueryBuilder` provides methods for all 9 resource types: systems, deployments, sampling features, procedures, properties, datastreams, observations, control streams, and commands.
161+
162+
Advanced consumers who already hold a collection descriptor and a discovered resource-URL map can use the pure factory directly:
163+
164+
```ts
165+
import {
166+
createCSAPIBuilder,
167+
type CSAPICollectionRef,
168+
} from '@camptocamp/ogc-client/csapi';
169+
170+
const collection: CSAPICollectionRef = {
171+
id: 'weather-stations',
172+
links: [],
173+
};
174+
const resourceUrls = new Map([['systems', 'https://api.example.org/systems']]);
175+
const builder = createCSAPIBuilder(collection, resourceUrls);
176+
```
177+
178+
Unlike `endpoint.csapi(...)`, `createCSAPIBuilder(collection, resourceUrls)` performs no discovery or network I/O. The endpoint facade is the preferred entry point for normal consumers.
162179

163180
### Why a separate import path?
164181

165-
The OGC Connected Systems standard is large — it spans 9 resource types across 2 specification parts with multiple response formats (GeoJSON, SWE Common, SensorML). By isolating CSAPI behind a sub-path export, users who only need WMS/WFS/WMTS/etc. don't pay the bundle-size cost for functionality they're not using. Modern bundlers (Webpack 5+, Vite, Rollup, esbuild) handle this automatically.
182+
The OGC Connected Systems standard is large — it spans 9 resource types across 2 specification parts with multiple response formats (GeoJSON, SWE Common, SensorML). By isolating CSAPI behind a dynamic boundary and sub-path export, users who only need WMS/WFS/WMTS/etc. don't pay the bundle-size cost for functionality they're not using. Modern bundlers (Webpack 5+, Vite, Rollup, esbuild) handle this automatically.

‎src/ogc-api/csapi/formats/sensorml/index.ts‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,23 @@
11
/**
2-
* SensorML 3.0 — public entry point for SensorML parsing and types.
2+
* SensorML 3.0 — internal barrel for SensorML parsing and types.
33
*
4-
* This barrel file re-exports the public API surface of the `sensorml/`
5-
* directory. All runtime values and compile-time types needed by
6-
* consumers are available from a single import path:
4+
* This barrel file collects the exports of the `sensorml/` directory. The
5+
* package's public CSAPI entry point selectively exposes the supported
6+
* consumer surface. Consumers import the parser and public types from that
7+
* package sub-path:
78
*
89
* ```typescript
910
* // Runtime values
10-
* import { parseSensorML30, SensorMLParseError } from '@camptocamp/ogc-client/csapi/formats/sensorml';
11+
* import { parseSensorML30 } from '@camptocamp/ogc-client/csapi';
1112
*
1213
* // Type-only imports
13-
* import type { PhysicalSystem, SensorMLProcess } from '@camptocamp/ogc-client/csapi/formats/sensorml';
14+
* import type { PhysicalSystem, SensorMLProcess } from '@camptocamp/ogc-client/csapi';
1415
* ```
1516
*
16-
* **Runtime exports:**
17+
* **Internal barrel exports:**
1718
* - {@link parseSensorML30} — main parser entry point (type discriminates
1819
* and delegates to sub-parsers)
19-
* - {@link SensorMLParseError} — error class thrown on parse failures
20+
* - {@link SensorMLParseError} — internal error class thrown on parse failures
2021
* - {@link parseCapabilityList} — standalone CapabilityList parser
2122
* - {@link parseCharacteristicList} — standalone CharacteristicList parser
2223
* - {@link parseDescribedObjectProperties} — shared DescribedObject helper

‎src/ogc-api/csapi/formats/sensorml/parser.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -402,7 +402,7 @@ export function parseAbstractPhysicalProcessProperties(
402402
*
403403
* @example
404404
* ```typescript
405-
* import { parseSensorML30 } from '@camptocamp/ogc-client/csapi/formats/sensorml';
405+
* import { parseSensorML30 } from '@camptocamp/ogc-client/csapi';
406406
*
407407
* const result = parseSensorML30(jsonFromServer);
408408
* switch (result.type) {

‎src/ogc-api/csapi/index.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,11 @@
2626
* @example
2727
* ```ts
2828
* import { OgcApiEndpoint } from '@camptocamp/ogc-client';
29-
* import {
30-
* createCSAPIBuilder,
31-
* parseDatastream,
32-
* } from '@camptocamp/ogc-client/csapi';
29+
* import { parseDatastream } from '@camptocamp/ogc-client/csapi';
3330
*
3431
* // 1. Endpoint → 2. Builder → 3. URL → 4. fetch → 5. parse
3532
* const endpoint = new OgcApiEndpoint('https://api.example.com');
36-
* const builder = await createCSAPIBuilder(endpoint, 'weather-stations');
33+
* const builder = await endpoint.csapi('weather-stations');
3734
* const url = builder.getDatastreams({ limit: 10 });
3835
* const response = await fetch(url, {
3936
* headers: { Authorization: 'Bearer ...' },
@@ -42,6 +39,12 @@
4239
* const datastreams = body.items.map(parseDatastream);
4340
* ```
4441
*
42+
* Advanced consumers who already hold a collection descriptor and a
43+
* discovered resource-URL map can instead call
44+
* `createCSAPIBuilder(collection, resourceUrls)`. That pure factory performs
45+
* no discovery or network I/O; `endpoint.csapi(collectionId)` is the preferred
46+
* entry point for normal consumers.
47+
*
4548
* ## Pagination
4649
*
4750
* All `get*()` list methods follow the OGC API Common pagination contract:

‎src/ogc-api/csapi/url_builder.ts‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -122,8 +122,8 @@ type ResourceSubPath =
122122
* const url = `${baseUrl}/collections/${collectionId}/systems?limit=50&bbox=-180,-90,180,90`;
123123
*
124124
* // After (using CSAPIQueryBuilder):
125-
* const endpoint = await new OgcApiEndpoint(baseUrl);
126-
* const builder = await createCSAPIBuilder(endpoint, collectionId);
125+
* const endpoint = new OgcApiEndpoint(baseUrl);
126+
* const builder = await endpoint.csapi(collectionId);
127127
* const url = builder.getSystems({ limit: 50, bbox: [-180, -90, 180, 90] });
128128
* ```
129129
*
@@ -134,10 +134,9 @@ type ResourceSubPath =
134134
* @example Complete workflow — list, filter, and navigate CSAPI resources:
135135
* ```ts
136136
* import { OgcApiEndpoint } from '@camptocamp/ogc-client';
137-
* import { createCSAPIBuilder } from '@camptocamp/ogc-client/csapi';
138137
*
139-
* const endpoint = await new OgcApiEndpoint('https://api.example.com');
140-
* const builder = await createCSAPIBuilder(endpoint, 'weather-stations');
138+
* const endpoint = new OgcApiEndpoint('https://api.example.com');
139+
* const builder = await endpoint.csapi('weather-stations');
141140
*
142141
* // List systems with spatial and text filters
143142
* const systemsUrl = builder.getSystems({

‎src/ogc-api/endpoint.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -225,7 +225,7 @@ ${e.message}`);
225225
*
226226
* @example
227227
* ```ts
228-
* const endpoint = await new OgcApiEndpoint('https://api.example.com');
228+
* const endpoint = new OgcApiEndpoint('https://api.example.com');
229229
* const collections = await endpoint.csapiCollections;
230230
* // => ['weather-stations', 'river-gauges']
231231
* ```
@@ -319,14 +319,14 @@ ${e.message}`);
319319
*
320320
* @example
321321
* ```ts
322-
* const endpoint = await new OgcApiEndpoint('https://api.example.com');
322+
* const endpoint = new OgcApiEndpoint('https://api.example.com');
323323
* if (await endpoint.hasConnectedSystems) {
324-
* const builder = await createCSAPIBuilder(endpoint, 'weather-stations');
324+
* const builder = await endpoint.csapi('weather-stations');
325325
* // ... build CSAPI queries
326326
* }
327327
* ```
328328
*
329-
* @see Use createCSAPIBuilder via '@camptocamp/ogc-client/csapi'
329+
* @see {@link csapi} for the preferred CSAPI builder entry point
330330
* @see {@link csapiCollections} to list available collections
331331
* @see https://docs.ogc.org/is/23-001/23-001.html
332332
*/

0 commit comments

Comments
 (0)