@lunora/bindings 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/analytics/index.d.mts

@@ -1,20 +1,20 @@
 import { LunoraError } from '@lunora/errors';
 /**
-* Structural types for the Analytics Engine write path.
-*
-* The real binding is workers-types' `AnalyticsEngineDataset`. We mirror it
-* **structurally** (`AnalyticsEngineDatasetLike`) so plain-object test doubles
-* satisfy the contract without pulling workerd into a unit test — the same
-* approach `@lunora/d1` takes with `D1DatabaseLike`
-* (`packages/d1/src/d1-client.ts`).
-*/
+ * Structural types for the Analytics Engine write path.
+ *
+ * The real binding is workers-types' `AnalyticsEngineDataset`. We mirror it
+ * **structurally** (`AnalyticsEngineDatasetLike`) so plain-object test doubles
+ * satisfy the contract without pulling workerd into a unit test — the same
+ * approach `@lunora/d1` takes with `D1DatabaseLike`
+ * (`packages/d1/src/d1-client.ts`).
+ */
 /**
-* One Analytics Engine data point, mirroring the positional shape
-* `writeDataPoint` accepts. AE stores up to 20 string `blobs`, up to 20 numeric
-* `doubles`, and exactly **one** `index` (the high-cardinality sampling key) per
-* data point — the SQL API later exposes them as `blob1..blob20`,
-* `double1..double20`, and `index1`.
-*/
+ * One Analytics Engine data point, mirroring the positional shape
+ * `writeDataPoint` accepts. AE stores up to 20 string `blobs`, up to 20 numeric
+ * `doubles`, and exactly **one** `index` (the high-cardinality sampling key) per
+ * data point — the SQL API later exposes them as `blob1..blob20`,
+ * `double1..double20`, and `index1`.
+ */
 interface AnalyticsEngineDataPoint {
   /** String columns, mapped positionally to `blob1..blob20`. */
   blobs?: (ArrayBuffer | null | string)[];
@@ -24,19 +24,19 @@ interface AnalyticsEngineDataPoint {
   indexes?: (ArrayBuffer | string)[];
 }
 /**
-* Minimal structural projection of workers-types' `AnalyticsEngineDataset`,
-* kept loose enough for a plain-object fake in unit tests. `writeDataPoint` is
-* fire-and-forget: it returns `void` and never throws on the hot path.
-*/
+ * Minimal structural projection of workers-types' `AnalyticsEngineDataset`,
+ * kept loose enough for a plain-object fake in unit tests. `writeDataPoint` is
+ * fire-and-forget: it returns `void` and never throws on the hot path.
+ */
 interface AnalyticsEngineDatasetLike {
   writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
 }
 /**
-* Named-field event handed to {@link AnalyticsClient.track}. Each field is
-* mapped to a positional AE column and the mapping recorded in a returned
-* {@link TrackSchema}, so the read side can reconstruct named columns from the
-* SQL API's positional `blobN`/`doubleN`/`index1` output.
-*/
+ * Named-field event handed to {@link AnalyticsClient.track}. Each field is
+ * mapped to a positional AE column and the mapping recorded in a returned
+ * {@link TrackSchema}, so the read side can reconstruct named columns from the
+ * SQL API's positional `blobN`/`doubleN`/`index1` output.
+ */
 interface TrackEvent {
   /** String dimensions → `blobs` (`blob1..blob20`), in object key order. */
   dimensions?: Record<string, string>;
@@ -53,11 +53,11 @@ interface TrackColumn {
   field: string;
 }
 /**
-* The field→column mapping {@link AnalyticsClient.track} records for one event
-* shape, so the read side can project the SQL API's positional columns back to
-* named fields. `name` is the logical event name; the column arrays are in the
-* same order the dimensions/metrics were written.
-*/
+ * The field→column mapping {@link AnalyticsClient.track} records for one event
+ * shape, so the read side can project the SQL API's positional columns back to
+ * named fields. `name` is the logical event name; the column arrays are in the
+ * same order the dimensions/metrics were written.
+ */
 interface TrackSchema {
   dimensions: TrackColumn[];
   index: TrackColumn | null;
@@ -65,41 +65,41 @@ interface TrackSchema {
   name: string;
 }
 /**
-* The write-side client bound to `ctx.analytics` (the generated context imports
-* this exact type as `import("@lunora/bindings/analytics").AnalyticsClient`). Telemetry
-* is fire-and-forget and sampled — never read a data point back in-handler.
-*/
+ * The write-side client bound to `ctx.analytics` (the generated context imports
+ * this exact type as `import("@lunora/bindings/analytics").AnalyticsClient`). Telemetry
+ * is fire-and-forget and sampled — never read a data point back in-handler.
+ */
 interface AnalyticsClient {
   /**
-  * Ergonomic named-field write: maps `{ dimensions, metrics, index }` to the
-  * positional layout, writes it, and returns the {@link TrackSchema} mapping
-  * (the logical `name` is recorded as the first blob, `blob1`).
-  */
+   * Ergonomic named-field write: maps `{ dimensions, metrics, index }` to the
+   * positional layout, writes it, and returns the {@link TrackSchema} mapping
+   * (the logical `name` is recorded as the first blob, `blob1`).
+   */
   track: (name: string, event?: TrackEvent) => TrackSchema;
   /**
-  * Write a raw positional data point. Enforces AE's per-data-point count
-  * caps (≤20 blobs, ≤20 doubles, ≤1 index) and byte budget (combined blobs
-  * ≤16 KiB, index ≤96 bytes, measured as UTF-8); overflow throws so a misuse
-  * surfaces in dev rather than being silently rejected by the platform.
-  */
+   * Write a raw positional data point. Enforces AE's per-data-point count
+   * caps (≤20 blobs, ≤20 doubles, ≤1 index) and byte budget (combined blobs
+   * ≤16 KiB, index ≤96 bytes, measured as UTF-8); overflow throws so a misuse
+   * surfaces in dev rather than being silently rejected by the platform.
+   */
   writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
 }
 /**
-* Wrap an Analytics Engine dataset binding in the write-side
-* {@link AnalyticsClient} bound to `ctx.analytics`.
-*
-* The binding is `env.ANALYTICS` (the self-describing
-* `analytics_engine_datasets` binding the config layer reconciles). Writes are
-* fire-and-forget and sampled — there is no return value to read in-handler.
-*
-* `writeDataPoint` enforces AE's per-data-point caps eagerly — both the count
-* caps (≤20 blobs, ≤20 doubles, ≤1 index) and the byte budget (combined blobs
-* ≤16 KiB, index ≤96 bytes, measured as UTF-8) — so a misuse throws in dev
-* instead of being silently rejected by the platform at the edge. `track` is
-* the ergonomic named-field path: it maps a
-* `{ dimensions, metrics, index }` object to the positional layout and returns
-* the field→column mapping the read side uses to reconstruct named columns.
-*/
+ * Wrap an Analytics Engine dataset binding in the write-side
+ * {@link AnalyticsClient} bound to `ctx.analytics`.
+ *
+ * The binding is `env.ANALYTICS` (the self-describing
+ * `analytics_engine_datasets` binding the config layer reconciles). Writes are
+ * fire-and-forget and sampled — there is no return value to read in-handler.
+ *
+ * `writeDataPoint` enforces AE's per-data-point caps eagerly — both the count
+ * caps (≤20 blobs, ≤20 doubles, ≤1 index) and the byte budget (combined blobs
+ * ≤16 KiB, index ≤96 bytes, measured as UTF-8) — so a misuse throws in dev
+ * instead of being silently rejected by the platform at the edge. `track` is
+ * the ergonomic named-field path: it maps a
+ * `{ dimensions, metrics, index }` object to the positional layout and returns
+ * the field→column mapping the read side uses to reconstruct named columns.
+ */
 declare const createAnalytics: (binding: AnalyticsEngineDatasetLike) => AnalyticsClient;
 /** Configuration for an {@link AnalyticsSqlClient}. */
 interface AnalyticsSqlConfig {
@@ -108,24 +108,24 @@ interface AnalyticsSqlConfig {
   /** API token with Analytics Engine read scope. A secret — never a binding. */
   apiToken: string;
   /**
-  * `fetch` implementation. Defaults to the global `fetch`; injected in tests
-  * so the SQL path never touches the network.
-  */
+   * `fetch` implementation. Defaults to the global `fetch`; injected in tests
+   * so the SQL path never touches the network.
+   */
   fetch?: typeof globalThis.fetch;
 }
 /**
-* One column descriptor in a SQL-API response's `meta` array: the column `name`
-* and the AE storage `type` (`String`, `Float64`, `DateTime`, …).
-*/
+ * One column descriptor in a SQL-API response's `meta` array: the column `name`
+ * and the AE storage `type` (`String`, `Float64`, `DateTime`, …).
+ */
 interface AnalyticsSqlColumnMeta {
   name: string;
   type: string;
 }
 /**
-* Parsed SQL-API result. AE returns `{ meta, data, rows, rows_before_limit_at_least }`;
-* we surface `columns` (from `meta`), the `rows` array of column→value records,
-* and the total `rowCount`.
-*/
+ * Parsed SQL-API result. AE returns `{ meta, data, rows, rows_before_limit_at_least }`;
+ * we surface `columns` (from `meta`), the `rows` array of column→value records,
+ * and the total `rowCount`.
+ */
 interface AnalyticsSqlResult {
   columns: AnalyticsSqlColumnMeta[];
   rowCount: number;
@@ -140,9 +140,9 @@ interface AnalyticsSqlClient {
   query: (sql: string) => Promise<AnalyticsSqlResult>;
 }
 /**
-* Build an {@link AnalyticsSqlClient}. Each `query` POSTs the raw SQL text to
-* the account's `analytics_engine/sql` endpoint with the bearer token, then
-* normalises AE's `{ meta, data, rows }` body into {@link AnalyticsSqlResult}.
-*/
+ * Build an {@link AnalyticsSqlClient}. Each `query` POSTs the raw SQL text to
+ * the account's `analytics_engine/sql` endpoint with the bearer token, then
+ * normalises AE's `{ meta, data, rows }` body into {@link AnalyticsSqlResult}.
+ */
 declare const createAnalyticsSqlClient: (config: AnalyticsSqlConfig) => AnalyticsSqlClient;
 export { type AnalyticsClient, type AnalyticsEngineDataPoint, type AnalyticsEngineDatasetLike, type AnalyticsSqlClient, type AnalyticsSqlColumnMeta, type AnalyticsSqlConfig, AnalyticsSqlError, type AnalyticsSqlResult, type TrackColumn, type TrackEvent, type TrackSchema, createAnalytics, createAnalyticsSqlClient };

package/dist/analytics/index.d.ts

@@ -1,20 +1,20 @@
 import { LunoraError } from '@lunora/errors';
 /**
-* Structural types for the Analytics Engine write path.
-*
-* The real binding is workers-types' `AnalyticsEngineDataset`. We mirror it
-* **structurally** (`AnalyticsEngineDatasetLike`) so plain-object test doubles
-* satisfy the contract without pulling workerd into a unit test — the same
-* approach `@lunora/d1` takes with `D1DatabaseLike`
-* (`packages/d1/src/d1-client.ts`).
-*/
+ * Structural types for the Analytics Engine write path.
+ *
+ * The real binding is workers-types' `AnalyticsEngineDataset`. We mirror it
+ * **structurally** (`AnalyticsEngineDatasetLike`) so plain-object test doubles
+ * satisfy the contract without pulling workerd into a unit test — the same
+ * approach `@lunora/d1` takes with `D1DatabaseLike`
+ * (`packages/d1/src/d1-client.ts`).
+ */
 /**
-* One Analytics Engine data point, mirroring the positional shape
-* `writeDataPoint` accepts. AE stores up to 20 string `blobs`, up to 20 numeric
-* `doubles`, and exactly **one** `index` (the high-cardinality sampling key) per
-* data point — the SQL API later exposes them as `blob1..blob20`,
-* `double1..double20`, and `index1`.
-*/
+ * One Analytics Engine data point, mirroring the positional shape
+ * `writeDataPoint` accepts. AE stores up to 20 string `blobs`, up to 20 numeric
+ * `doubles`, and exactly **one** `index` (the high-cardinality sampling key) per
+ * data point — the SQL API later exposes them as `blob1..blob20`,
+ * `double1..double20`, and `index1`.
+ */
 interface AnalyticsEngineDataPoint {
   /** String columns, mapped positionally to `blob1..blob20`. */
   blobs?: (ArrayBuffer | null | string)[];
@@ -24,19 +24,19 @@ interface AnalyticsEngineDataPoint {
   indexes?: (ArrayBuffer | string)[];
 }
 /**
-* Minimal structural projection of workers-types' `AnalyticsEngineDataset`,
-* kept loose enough for a plain-object fake in unit tests. `writeDataPoint` is
-* fire-and-forget: it returns `void` and never throws on the hot path.
-*/
+ * Minimal structural projection of workers-types' `AnalyticsEngineDataset`,
+ * kept loose enough for a plain-object fake in unit tests. `writeDataPoint` is
+ * fire-and-forget: it returns `void` and never throws on the hot path.
+ */
 interface AnalyticsEngineDatasetLike {
   writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
 }
 /**
-* Named-field event handed to {@link AnalyticsClient.track}. Each field is
-* mapped to a positional AE column and the mapping recorded in a returned
-* {@link TrackSchema}, so the read side can reconstruct named columns from the
-* SQL API's positional `blobN`/`doubleN`/`index1` output.
-*/
+ * Named-field event handed to {@link AnalyticsClient.track}. Each field is
+ * mapped to a positional AE column and the mapping recorded in a returned
+ * {@link TrackSchema}, so the read side can reconstruct named columns from the
+ * SQL API's positional `blobN`/`doubleN`/`index1` output.
+ */
 interface TrackEvent {
   /** String dimensions → `blobs` (`blob1..blob20`), in object key order. */
   dimensions?: Record<string, string>;
@@ -53,11 +53,11 @@ interface TrackColumn {
   field: string;
 }
 /**
-* The field→column mapping {@link AnalyticsClient.track} records for one event
-* shape, so the read side can project the SQL API's positional columns back to
-* named fields. `name` is the logical event name; the column arrays are in the
-* same order the dimensions/metrics were written.
-*/
+ * The field→column mapping {@link AnalyticsClient.track} records for one event
+ * shape, so the read side can project the SQL API's positional columns back to
+ * named fields. `name` is the logical event name; the column arrays are in the
+ * same order the dimensions/metrics were written.
+ */
 interface TrackSchema {
   dimensions: TrackColumn[];
   index: TrackColumn | null;
@@ -65,41 +65,41 @@ interface TrackSchema {
   name: string;
 }
 /**
-* The write-side client bound to `ctx.analytics` (the generated context imports
-* this exact type as `import("@lunora/bindings/analytics").AnalyticsClient`). Telemetry
-* is fire-and-forget and sampled — never read a data point back in-handler.
-*/
+ * The write-side client bound to `ctx.analytics` (the generated context imports
+ * this exact type as `import("@lunora/bindings/analytics").AnalyticsClient`). Telemetry
+ * is fire-and-forget and sampled — never read a data point back in-handler.
+ */
 interface AnalyticsClient {
   /**
-  * Ergonomic named-field write: maps `{ dimensions, metrics, index }` to the
-  * positional layout, writes it, and returns the {@link TrackSchema} mapping
-  * (the logical `name` is recorded as the first blob, `blob1`).
-  */
+   * Ergonomic named-field write: maps `{ dimensions, metrics, index }` to the
+   * positional layout, writes it, and returns the {@link TrackSchema} mapping
+   * (the logical `name` is recorded as the first blob, `blob1`).
+   */
   track: (name: string, event?: TrackEvent) => TrackSchema;
   /**
-  * Write a raw positional data point. Enforces AE's per-data-point count
-  * caps (≤20 blobs, ≤20 doubles, ≤1 index) and byte budget (combined blobs
-  * ≤16 KiB, index ≤96 bytes, measured as UTF-8); overflow throws so a misuse
-  * surfaces in dev rather than being silently rejected by the platform.
-  */
+   * Write a raw positional data point. Enforces AE's per-data-point count
+   * caps (≤20 blobs, ≤20 doubles, ≤1 index) and byte budget (combined blobs
+   * ≤16 KiB, index ≤96 bytes, measured as UTF-8); overflow throws so a misuse
+   * surfaces in dev rather than being silently rejected by the platform.
+   */
   writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
 }
 /**
-* Wrap an Analytics Engine dataset binding in the write-side
-* {@link AnalyticsClient} bound to `ctx.analytics`.
-*
-* The binding is `env.ANALYTICS` (the self-describing
-* `analytics_engine_datasets` binding the config layer reconciles). Writes are
-* fire-and-forget and sampled — there is no return value to read in-handler.
-*
-* `writeDataPoint` enforces AE's per-data-point caps eagerly — both the count
-* caps (≤20 blobs, ≤20 doubles, ≤1 index) and the byte budget (combined blobs
-* ≤16 KiB, index ≤96 bytes, measured as UTF-8) — so a misuse throws in dev
-* instead of being silently rejected by the platform at the edge. `track` is
-* the ergonomic named-field path: it maps a
-* `{ dimensions, metrics, index }` object to the positional layout and returns
-* the field→column mapping the read side uses to reconstruct named columns.
-*/
+ * Wrap an Analytics Engine dataset binding in the write-side
+ * {@link AnalyticsClient} bound to `ctx.analytics`.
+ *
+ * The binding is `env.ANALYTICS` (the self-describing
+ * `analytics_engine_datasets` binding the config layer reconciles). Writes are
+ * fire-and-forget and sampled — there is no return value to read in-handler.
+ *
+ * `writeDataPoint` enforces AE's per-data-point caps eagerly — both the count
+ * caps (≤20 blobs, ≤20 doubles, ≤1 index) and the byte budget (combined blobs
+ * ≤16 KiB, index ≤96 bytes, measured as UTF-8) — so a misuse throws in dev
+ * instead of being silently rejected by the platform at the edge. `track` is
+ * the ergonomic named-field path: it maps a
+ * `{ dimensions, metrics, index }` object to the positional layout and returns
+ * the field→column mapping the read side uses to reconstruct named columns.
+ */
 declare const createAnalytics: (binding: AnalyticsEngineDatasetLike) => AnalyticsClient;
 /** Configuration for an {@link AnalyticsSqlClient}. */
 interface AnalyticsSqlConfig {
@@ -108,24 +108,24 @@ interface AnalyticsSqlConfig {
   /** API token with Analytics Engine read scope. A secret — never a binding. */
   apiToken: string;
   /**
-  * `fetch` implementation. Defaults to the global `fetch`; injected in tests
-  * so the SQL path never touches the network.
-  */
+   * `fetch` implementation. Defaults to the global `fetch`; injected in tests
+   * so the SQL path never touches the network.
+   */
   fetch?: typeof globalThis.fetch;
 }
 /**
-* One column descriptor in a SQL-API response's `meta` array: the column `name`
-* and the AE storage `type` (`String`, `Float64`, `DateTime`, …).
-*/
+ * One column descriptor in a SQL-API response's `meta` array: the column `name`
+ * and the AE storage `type` (`String`, `Float64`, `DateTime`, …).
+ */
 interface AnalyticsSqlColumnMeta {
   name: string;
   type: string;
 }
 /**
-* Parsed SQL-API result. AE returns `{ meta, data, rows, rows_before_limit_at_least }`;
-* we surface `columns` (from `meta`), the `rows` array of column→value records,
-* and the total `rowCount`.
-*/
+ * Parsed SQL-API result. AE returns `{ meta, data, rows, rows_before_limit_at_least }`;
+ * we surface `columns` (from `meta`), the `rows` array of column→value records,
+ * and the total `rowCount`.
+ */
 interface AnalyticsSqlResult {
   columns: AnalyticsSqlColumnMeta[];
   rowCount: number;
@@ -140,9 +140,9 @@ interface AnalyticsSqlClient {
   query: (sql: string) => Promise<AnalyticsSqlResult>;
 }
 /**
-* Build an {@link AnalyticsSqlClient}. Each `query` POSTs the raw SQL text to
-* the account's `analytics_engine/sql` endpoint with the bearer token, then
-* normalises AE's `{ meta, data, rows }` body into {@link AnalyticsSqlResult}.
-*/
+ * Build an {@link AnalyticsSqlClient}. Each `query` POSTs the raw SQL text to
+ * the account's `analytics_engine/sql` endpoint with the bearer token, then
+ * normalises AE's `{ meta, data, rows }` body into {@link AnalyticsSqlResult}.
+ */
 declare const createAnalyticsSqlClient: (config: AnalyticsSqlConfig) => AnalyticsSqlClient;
 export { type AnalyticsClient, type AnalyticsEngineDataPoint, type AnalyticsEngineDatasetLike, type AnalyticsSqlClient, type AnalyticsSqlColumnMeta, type AnalyticsSqlConfig, AnalyticsSqlError, type AnalyticsSqlResult, type TrackColumn, type TrackEvent, type TrackSchema, createAnalytics, createAnalyticsSqlClient };