From 39841baa5b9b703907a62647e3f36b3db6404aa2 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Wed, 29 Oct 2025 16:21:43 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`549-exp?= =?UTF-8?q?lorer`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @alexanderkirtzel. * https://github.com/elbwalker/walkerOS/pull/552#issuecomment-3462100353 The following files were modified: * `apps/quickstart/src/mapping-test.ts` * `packages/core/src/schemas/schema-builder.ts` * `packages/server/destinations/gcp/src/bigquery/examples/env.ts` --- apps/quickstart/src/mapping-test.ts | 8 +- packages/core/src/schemas/schema-builder.ts | 94 ++++++------------- .../gcp/src/bigquery/examples/env.ts | 6 +- 3 files changed, 38 insertions(+), 70 deletions(-) diff --git a/apps/quickstart/src/mapping-test.ts b/apps/quickstart/src/mapping-test.ts index c305426b..25737985 100644 --- a/apps/quickstart/src/mapping-test.ts +++ b/apps/quickstart/src/mapping-test.ts @@ -8,6 +8,12 @@ import { startFlow } from '@walkeros/collector'; import type { WalkerOS } from '@walkeros/core'; +/** + * Runs end-to-end mapping tests for the Walker OS collector and logs the observed results. + * + * Configures a console destination with destination-level mappings (product view/add and order complete with a computed tax), + * sends several test events to verify mapping behavior, then creates a custom source with a source-level mapping and exercises it. + */ async function testMapping() { console.log('\n🧪 Testing walkerOS Mapping System\n'); console.log('='.repeat(60)); @@ -164,4 +170,4 @@ async function testMapping() { } // Run tests -testMapping().catch(console.error); +testMapping().catch(console.error); \ No newline at end of file diff --git a/packages/core/src/schemas/schema-builder.ts b/packages/core/src/schemas/schema-builder.ts index 2ffe0e33..f963b544 100644 --- a/packages/core/src/schemas/schema-builder.ts +++ b/packages/core/src/schemas/schema-builder.ts @@ -49,25 +49,11 @@ export interface PropertyDef { } /** - * Create object schema from property definitions + * Builds a top-level JSON Schema object from a map of property definitions. * - * @param properties - Property definitions - * @param title - Optional schema title - * @returns JSON Schema - * - * @example - * const schema = createObjectSchema({ - * pixelId: { - * type: 'string', - * required: true, - * pattern: '^[0-9]+$', - * description: 'Your Meta Pixel ID', - * }, - * eventName: { - * type: 'string', - * enum: ['PageView', 'Purchase'], - * }, - * }, 'Meta Pixel Settings'); + * @param properties - Map of property names to their schema definitions (`PropertyDef`) + * @param title - Optional title to set on the resulting schema + * @returns The assembled JSON Schema object with `type: "object"`, `properties` populated from `properties`, and `required` set for any properties marked required */ export function createObjectSchema( properties: Record, @@ -123,8 +109,13 @@ export function createObjectSchema( } /** - * Create property schema from definition - * Helper for nested properties + * Builds a JSON Schema fragment for a single property definition. + * + * Recursively includes nested object properties and array item schemas when the definition + * describes an object or an array. + * + * @param def - The PropertyDef describing the property's type, constraints, defaults and any nested properties/items. + * @returns A JSON Schema object representing the property, suitable for inclusion in a parent schema's `properties` or `items`. */ function createPropertySchema(def: PropertyDef): Record { const property: Record = { @@ -158,27 +149,13 @@ function createPropertySchema(def: PropertyDef): Record { } /** - * Create array schema - * - * @param itemDef - Definition for array items - * @param options - Optional array constraints - * @returns JSON Schema - * - * @example - * // Simple string array - * const tagsSchema = createArraySchema({ type: 'string' }); + * Builds a JSON Schema for an array whose items follow the provided property definition. * - * // Tuple (loop pattern) - exactly 2 items - * const loopSchema = createArraySchema( - * { type: 'object' }, - * { minItems: 2, maxItems: 2 } - * ); + * Supports optional constraints: `minItems`, `maxItems`, `description`, and `title`. * - * // Array with enum - * const includeSchema = createArraySchema({ - * type: 'string', - * enum: ['data', 'context', 'globals'], - * }); + * @param itemDef - Definition for each array item + * @param options - Optional array constraints (minItems, maxItems, description, title) + * @returns A JSONSchema describing the array with `items` set to the schema for `itemDef` and any provided constraints */ export function createArraySchema( itemDef: PropertyDef, @@ -203,19 +180,12 @@ export function createArraySchema( } /** - * Create enum schema - * - * @param values - Allowed values - * @param type - Value type ('string' or 'number') - * @param options - Optional constraints - * @returns JSON Schema + * Builds a JSON Schema that restricts values to the provided enum members. * - * @example - * const eventTypeSchema = createEnumSchema( - * ['PageView', 'Purchase', 'AddToCart'], - * 'string', - * { description: 'Meta Pixel standard event' } - * ); + * @param values - Allowed enum values + * @param type - The JSON Schema primitive type for the enum values ('string' or 'number') + * @param options - Optional metadata such as `description` and `title` + * @returns A JSON Schema object with `type` and `enum` set to the provided values */ export function createEnumSchema( values: readonly string[] | readonly number[], @@ -237,22 +207,12 @@ export function createEnumSchema( } /** - * Create tuple schema (Loop pattern) - * - * Creates an array schema with exactly 2 items, which the Explorer - * type detector recognizes as a "loop" pattern. - * - * @param firstItem - Definition for first element (source) - * @param secondItem - Definition for second element (transform) - * @param description - Optional description - * @returns JSON Schema with minItems=2, maxItems=2 + * Builds a JSON Schema for a two-element tuple representing a loop pattern. * - * @example - * const loopSchema = createTupleSchema( - * { type: 'string' }, - * { type: 'object' }, - * 'Loop: [source, transform]' - * ); + * @param firstItem - Definition for the first element (source). Note: the current implementation does not apply this definition to the produced schema. + * @param secondItem - Definition for the second element (transform). Note: the current implementation does not apply this definition to the produced schema. + * @param description - Optional description for the tuple schema. + * @returns A JSON Schema describing an array with exactly two items (`minItems=2`, `maxItems=2`). */ export function createTupleSchema( firstItem: PropertyDef, @@ -268,4 +228,4 @@ export function createTupleSchema( description || 'Tuple with exactly 2 elements [source, transform]', }, ); -} +} \ No newline at end of file diff --git a/packages/server/destinations/gcp/src/bigquery/examples/env.ts b/packages/server/destinations/gcp/src/bigquery/examples/env.ts index df6c5fbb..a5fc883a 100644 --- a/packages/server/destinations/gcp/src/bigquery/examples/env.ts +++ b/packages/server/destinations/gcp/src/bigquery/examples/env.ts @@ -11,7 +11,9 @@ import type { Env } from '../types'; const noop = () => {}; /** - * Mock BigQuery client class that simulates dataset/table operations + * Creates a mock BigQuery client class that records dataset, table, and insert invocations for tests. + * + * @returns A MockBigQuery class whose instances expose `calls` (array of recorded calls), `options` (constructor options), methods `dataset`, `table`, and `insert`, and a `mockFn` getter for backwards compatibility. */ function createMockBigQuery() { return class MockBigQuery { @@ -55,4 +57,4 @@ export const push: Env = { get BigQuery() { return createMockBigQuery() as unknown as Env['BigQuery']; }, -}; +}; \ No newline at end of file