@objectstack/spec 6.5.0 → 6.6.0

package/dist/cloud/index.mjs

@@ -6241,6 +6241,136 @@ var PageSchema = lazySchema(() => z.object({
     });
   }
 }));
+var SortNodeSchema = lazySchema(() => z.object({
+  field: z.string(),
+  order: z.enum(["asc", "desc"]).default("asc")
+}));
+var AggregationFunction = z.enum([
+  "count",
+  "sum",
+  "avg",
+  "min",
+  "max",
+  "count_distinct",
+  "array_agg",
+  "string_agg"
+]);
+var DateGranularity = z.enum(["day", "week", "month", "quarter", "year"]);
+var GroupByNodeSchema = lazySchema(() => z.union([
+  z.string(),
+  z.object({
+    field: z.string().describe("Field to group by"),
+    dateGranularity: DateGranularity.optional().describe("Bucket date values into uniform periods (day/week/month/quarter/year)"),
+    /** Optional alias for the projected group value (defaults to `field`). */
+    alias: z.string().optional().describe("Alias for the projected group value")
+  })
+]));
+var AggregationNodeSchema = lazySchema(() => z.object({
+  function: AggregationFunction.describe("Aggregation function"),
+  field: z.string().optional().describe("Field to aggregate (optional for COUNT(*))"),
+  alias: z.string().describe("Result column alias"),
+  distinct: z.boolean().optional().describe("Apply DISTINCT before aggregation"),
+  filter: FilterConditionSchema.optional().describe("Filter/Condition to apply to the aggregation (FILTER WHERE clause)")
+}));
+var JoinType = z.enum(["inner", "left", "right", "full"]);
+var JoinStrategy = z.enum(["auto", "database", "hash", "loop"]);
+var JoinNodeSchema = z.lazy(
+  () => z.object({
+    type: JoinType.describe("Join type"),
+    strategy: JoinStrategy.optional().describe("Execution strategy hint"),
+    object: z.string().describe("Object/table to join"),
+    alias: z.string().optional().describe("Table alias"),
+    on: FilterConditionSchema.describe("Join condition"),
+    subquery: z.lazy(() => QuerySchema).optional().describe("Subquery instead of object")
+  })
+);
+var WindowFunction = z.enum([
+  "row_number",
+  "rank",
+  "dense_rank",
+  "percent_rank",
+  "lag",
+  "lead",
+  "first_value",
+  "last_value",
+  "sum",
+  "avg",
+  "count",
+  "min",
+  "max"
+]);
+var WindowSpecSchema = lazySchema(() => z.object({
+  partitionBy: z.array(z.string()).optional().describe("PARTITION BY fields"),
+  orderBy: z.array(SortNodeSchema).optional().describe("ORDER BY specification"),
+  frame: z.object({
+    type: z.enum(["rows", "range"]).optional(),
+    start: z.string().optional().describe('Frame start (e.g., "UNBOUNDED PRECEDING", "1 PRECEDING")'),
+    end: z.string().optional().describe('Frame end (e.g., "CURRENT ROW", "1 FOLLOWING")')
+  }).optional().describe("Window frame specification")
+}));
+var WindowFunctionNodeSchema = lazySchema(() => z.object({
+  function: WindowFunction.describe("Window function name"),
+  field: z.string().optional().describe("Field to operate on (for aggregate window functions)"),
+  alias: z.string().describe("Result column alias"),
+  over: WindowSpecSchema.describe("Window specification (OVER clause)")
+}));
+var FieldNodeSchema = z.lazy(
+  () => z.union([
+    z.string(),
+    // Primitive field: "name"
+    z.object({
+      field: z.string(),
+      // Relationship field: "owner"
+      fields: z.array(FieldNodeSchema).optional(),
+      // Nested select: ["name", "email"]
+      alias: z.string().optional()
+    })
+  ])
+);
+var FullTextSearchSchema = lazySchema(() => z.object({
+  query: z.string().describe("Search query text"),
+  fields: z.array(z.string()).optional().describe("Fields to search in (if not specified, searches all text fields)"),
+  fuzzy: z.boolean().optional().default(false).describe("Enable fuzzy matching (tolerates typos)"),
+  operator: z.enum(["and", "or"]).optional().default("or").describe("Logical operator between terms"),
+  boost: z.record(z.string(), z.number()).optional().describe("Field-specific relevance boosting (field name -> boost factor)"),
+  minScore: z.number().optional().describe("Minimum relevance score threshold"),
+  language: z.string().optional().describe('Language for text analysis (e.g., "en", "zh", "es")'),
+  highlight: z.boolean().optional().default(false).describe("Enable search result highlighting")
+}));
+var BaseQuerySchema = z.object({
+  /** Target Entity */
+  object: z.string().describe("Object name (e.g. account)"),
+  /** Select Clause */
+  fields: z.array(FieldNodeSchema).optional().describe("Fields to retrieve"),
+  /** Where Clause (Filtering) */
+  where: FilterConditionSchema.optional().describe("Filtering criteria (WHERE)"),
+  /** Full-Text Search */
+  search: FullTextSearchSchema.optional().describe("Full-text search configuration ($search parameter)"),
+  /** Order By Clause (Sorting) */
+  orderBy: z.array(SortNodeSchema).optional().describe("Sorting instructions (ORDER BY)"),
+  /** Pagination */
+  limit: z.number().optional().describe("Max records to return (LIMIT)"),
+  offset: z.number().optional().describe("Records to skip (OFFSET)"),
+  top: z.number().optional().describe("Alias for limit (OData compatibility)"),
+  cursor: z.record(z.string(), z.unknown()).optional().describe("Cursor for keyset pagination"),
+  /** Joins */
+  joins: z.array(JoinNodeSchema).optional().describe("Explicit Table Joins"),
+  /** Aggregations */
+  aggregations: z.array(AggregationNodeSchema).optional().describe("Aggregation functions"),
+  /** Group By Clause */
+  groupBy: z.array(GroupByNodeSchema).optional().describe("GROUP BY targets (strings or `{field, dateGranularity?}` objects for date bucketing)"),
+  /** Having Clause */
+  having: FilterConditionSchema.optional().describe("HAVING clause for aggregation filtering"),
+  /** Window Functions */
+  windowFunctions: z.array(WindowFunctionNodeSchema).optional().describe("Window functions with OVER clause"),
+  /** Subquery flag */
+  distinct: z.boolean().optional().describe("SELECT DISTINCT flag")
+});
+var QuerySchema = lazySchema(() => BaseQuerySchema.extend({
+  expand: z.lazy(() => z.record(z.string(), QuerySchema)).optional().describe(
+    "Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select, filter, sort, and further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3."
+  )
+}));
 var ChartTypeSchema = lazySchema(() => z.enum([
   // Comparison
   "bar",
@@ -6319,7 +6449,22 @@ var ChartSeriesSchema = lazySchema(() => z.object({
   /** Stacking group */
   stack: z.string().optional().describe("Stack identifier to group series"),
   /** Axis binding */
-  yAxis: z.enum(["left", "right"]).default("left").describe("Bind to specific Y-Axis")
+  yAxis: z.enum(["left", "right"]).default("left").describe("Bind to specific Y-Axis"),
+  /**
+   * Series role.
+   *
+   * - `'primary'` (default) — normal styling using the chart palette.
+   * - `'comparison'` — secondary period-over-period overlay; renderers
+   *   render it muted (lower opacity, dashed stroke for line/area,
+   *   lighter fill for bars) so it visually backgrounds against the
+   *   primary series. Pair with `DashboardWidget.compareTo` on data-
+   *   bound charts; for hand-authored series, set it directly.
+   */
+  variant: z.enum(["primary", "comparison"]).default("primary").optional().describe("Series visual role"),
+  /** Override stroke dash pattern (e.g. "4 4" for dashed lines). */
+  dashArray: z.string().optional().describe("SVG stroke-dasharray override"),
+  /** Override series opacity (0–1). */
+  opacity: z.number().min(0).max(1).optional().describe("Series opacity override")
 }));
 var ChartAnnotationSchema = lazySchema(() => z.object({
   type: z.enum(["line", "region"]).default("line"),
@@ -6450,8 +6595,46 @@ var DashboardWidgetSchema = lazySchema(() => z.object({
   object: z.string().optional().describe("Data source object name"),
   /** Data Filter (MongoDB-style FilterCondition) */
   filter: FilterConditionSchema.optional().describe("Data filter criteria"),
+  /**
+   * Period-over-period comparison primitive.
+   *
+   * When set, the renderer runs a second query against a shifted time
+   * window and surfaces the delta (metric widgets show a secondary
+   * value + arrow; chart widgets render a muted/dashed overlay series).
+   *
+   * - `'previousPeriod'` — auto-detect the comparison window from the
+   *   widget's `filter` date macros (e.g. `{current_month_start}` →
+   *   `{last_month_start}`). Falls back to no comparison when the
+   *   filter contains no resolvable date range.
+   * - `'previousYear'` — shift the resolved filter window back by one
+   *   calendar year.
+   * - `{ offset: '7d' | '1M' | '1y' }` — shift by an explicit
+   *   ISO-8601-like duration. Units: `d` (days), `w` (weeks),
+   *   `M` (months), `y` (years).
+   */
+  compareTo: z.union([
+    z.literal("previousPeriod"),
+    z.literal("previousYear"),
+    z.object({
+      offset: z.string().regex(/^\d+[dwMy]$/, 'Offset must match <N>(d|w|M|y), e.g. "7d", "1M", "1y"')
+    })
+  ]).optional().describe("Period-over-period comparison window"),
   /** Category Field (X-Axis / Group By) */
   categoryField: z.string().optional().describe("Field for grouping (X-Axis)"),
+  /**
+   * Date Bucketing Granularity for `categoryField`
+   *
+   * When set and `categoryField` references a date/datetime field, the engine
+   * buckets values into uniform `day` / `week` / `month` / `quarter` / `year`
+   * periods server-side (PostgreSQL `date_trunc`, MySQL `date_format`, SQLite
+   * `strftime`, MongoDB `$dateTrunc`; falls back to in-memory ISO-8601
+   * bucketing otherwise). Without this, raw timestamps are grouped verbatim
+   * which typically yields one bucket per row — making time-series charts
+   * appear flat.
+   *
+   * Mirrors the `dateGranularity` shape of {@link GroupByNodeSchema}.
+   */
+  categoryGranularity: DateGranularity.optional().describe("Bucket categoryField date values into day/week/month/quarter/year periods"),
   /** Value Field (Y-Axis) */
   valueField: z.string().optional().describe("Field for values (Y-Axis)"),
   /** Aggregate operation */
@@ -8198,138 +8381,6 @@ lazySchema(() => z.object({
     email: z.string().optional()
   }).optional().describe("Current user info shortcut")
 }));
-var SortNodeSchema = lazySchema(() => z.object({
-  field: z.string(),
-  order: z.enum(["asc", "desc"]).default("asc")
-}));
-var AggregationFunction = z.enum([
-  "count",
-  "sum",
-  "avg",
-  "min",
-  "max",
-  "count_distinct",
-  "array_agg",
-  "string_agg"
-]);
-var DateGranularity = z.enum(["day", "week", "month", "quarter", "year"]);
-var GroupByNodeSchema = lazySchema(() => z.union([
-  z.string(),
-  z.object({
-    field: z.string().describe("Field to group by"),
-    dateGranularity: DateGranularity.optional().describe("Bucket date values into uniform periods (day/week/month/quarter/year)"),
-    /** Optional alias for the projected group value (defaults to `field`). */
-    alias: z.string().optional().describe("Alias for the projected group value")
-  })
-]));
-var AggregationNodeSchema = lazySchema(() => z.object({
-  function: AggregationFunction.describe("Aggregation function"),
-  field: z.string().optional().describe("Field to aggregate (optional for COUNT(*))"),
-  alias: z.string().describe("Result column alias"),
-  distinct: z.boolean().optional().describe("Apply DISTINCT before aggregation"),
-  filter: FilterConditionSchema.optional().describe("Filter/Condition to apply to the aggregation (FILTER WHERE clause)")
-}));
-var JoinType = z.enum(["inner", "left", "right", "full"]);
-var JoinStrategy = z.enum(["auto", "database", "hash", "loop"]);
-var JoinNodeSchema = z.lazy(
-  () => z.object({
-    type: JoinType.describe("Join type"),
-    strategy: JoinStrategy.optional().describe("Execution strategy hint"),
-    object: z.string().describe("Object/table to join"),
-    alias: z.string().optional().describe("Table alias"),
-    on: FilterConditionSchema.describe("Join condition"),
-    subquery: z.lazy(() => QuerySchema).optional().describe("Subquery instead of object")
-  })
-);
-var WindowFunction = z.enum([
-  "row_number",
-  "rank",
-  "dense_rank",
-  "percent_rank",
-  "lag",
-  "lead",
-  "first_value",
-  "last_value",
-  "sum",
-  "avg",
-  "count",
-  "min",
-  "max"
-]);
-var WindowSpecSchema = lazySchema(() => z.object({
-  partitionBy: z.array(z.string()).optional().describe("PARTITION BY fields"),
-  orderBy: z.array(SortNodeSchema).optional().describe("ORDER BY specification"),
-  frame: z.object({
-    type: z.enum(["rows", "range"]).optional(),
-    start: z.string().optional().describe('Frame start (e.g., "UNBOUNDED PRECEDING", "1 PRECEDING")'),
-    end: z.string().optional().describe('Frame end (e.g., "CURRENT ROW", "1 FOLLOWING")')
-  }).optional().describe("Window frame specification")
-}));
-var WindowFunctionNodeSchema = lazySchema(() => z.object({
-  function: WindowFunction.describe("Window function name"),
-  field: z.string().optional().describe("Field to operate on (for aggregate window functions)"),
-  alias: z.string().describe("Result column alias"),
-  over: WindowSpecSchema.describe("Window specification (OVER clause)")
-}));
-var FieldNodeSchema = z.lazy(
-  () => z.union([
-    z.string(),
-    // Primitive field: "name"
-    z.object({
-      field: z.string(),
-      // Relationship field: "owner"
-      fields: z.array(FieldNodeSchema).optional(),
-      // Nested select: ["name", "email"]
-      alias: z.string().optional()
-    })
-  ])
-);
-var FullTextSearchSchema = lazySchema(() => z.object({
-  query: z.string().describe("Search query text"),
-  fields: z.array(z.string()).optional().describe("Fields to search in (if not specified, searches all text fields)"),
-  fuzzy: z.boolean().optional().default(false).describe("Enable fuzzy matching (tolerates typos)"),
-  operator: z.enum(["and", "or"]).optional().default("or").describe("Logical operator between terms"),
-  boost: z.record(z.string(), z.number()).optional().describe("Field-specific relevance boosting (field name -> boost factor)"),
-  minScore: z.number().optional().describe("Minimum relevance score threshold"),
-  language: z.string().optional().describe('Language for text analysis (e.g., "en", "zh", "es")'),
-  highlight: z.boolean().optional().default(false).describe("Enable search result highlighting")
-}));
-var BaseQuerySchema = z.object({
-  /** Target Entity */
-  object: z.string().describe("Object name (e.g. account)"),
-  /** Select Clause */
-  fields: z.array(FieldNodeSchema).optional().describe("Fields to retrieve"),
-  /** Where Clause (Filtering) */
-  where: FilterConditionSchema.optional().describe("Filtering criteria (WHERE)"),
-  /** Full-Text Search */
-  search: FullTextSearchSchema.optional().describe("Full-text search configuration ($search parameter)"),
-  /** Order By Clause (Sorting) */
-  orderBy: z.array(SortNodeSchema).optional().describe("Sorting instructions (ORDER BY)"),
-  /** Pagination */
-  limit: z.number().optional().describe("Max records to return (LIMIT)"),
-  offset: z.number().optional().describe("Records to skip (OFFSET)"),
-  top: z.number().optional().describe("Alias for limit (OData compatibility)"),
-  cursor: z.record(z.string(), z.unknown()).optional().describe("Cursor for keyset pagination"),
-  /** Joins */
-  joins: z.array(JoinNodeSchema).optional().describe("Explicit Table Joins"),
-  /** Aggregations */
-  aggregations: z.array(AggregationNodeSchema).optional().describe("Aggregation functions"),
-  /** Group By Clause */
-  groupBy: z.array(GroupByNodeSchema).optional().describe("GROUP BY targets (strings or `{field, dateGranularity?}` objects for date bucketing)"),
-  /** Having Clause */
-  having: FilterConditionSchema.optional().describe("HAVING clause for aggregation filtering"),
-  /** Window Functions */
-  windowFunctions: z.array(WindowFunctionNodeSchema).optional().describe("Window functions with OVER clause"),
-  /** Subquery flag */
-  distinct: z.boolean().optional().describe("SELECT DISTINCT flag")
-});
-var QuerySchema = lazySchema(() => BaseQuerySchema.extend({
-  expand: z.lazy(() => z.record(z.string(), QuerySchema)).optional().describe(
-    "Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select, filter, sort, and further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3."
-  )
-}));
-
-// src/data/mapping.zod.ts
 var TransformType = z.enum([
   "none",
   // Direct copy