semanticdb-v2 2.0.0-alpha.1

package/dist/executor/types.d.ts

@@ -0,0 +1,118 @@
+import type { OperatorRegistry } from '../operators/index';
+import type { CoreComputeProvider, DataRow, SqlParameters } from '../physical/index';
+import type { DatabaseConnection } from '../physical/index';
+import type { LogicalPlan, QueryLineage } from '../planner/index';
+import type { SchemaMappingRegistry } from '../schema-mappings/index';
+import type { ResolvedSemanticSchema, SemanticSchemaDraft, SemanticTypeRegistry } from '../semantic-types/index';
+import type { LogicformType } from '../logicform-types';
+import type { QueryCacheExecutionOptions } from '../cache/index';
+import type { Permissions } from '../permissions/index';
+import type { CustomFunctions } from '../custom-functions/index';
+import type { SemanticDBPlugin } from '../plugins/index';
+export type ExecuteProgressEvent = {
+    readonly stage: 'started';
+    readonly logicform: LogicformType;
+    readonly partialResult: PartialExecuteResult;
+} | {
+    readonly stage: 'validated';
+    readonly schema: ResolvedSemanticSchema;
+    readonly partialResult: PartialExecuteResult;
+} | {
+    readonly stage: 'normalized';
+    readonly normedLogicform: LogicformType;
+    readonly partialResult: PartialExecuteResult;
+} | {
+    readonly stage: 'planned';
+    readonly plan: LogicalPlan;
+    readonly partialResult: PartialExecuteResult;
+} | {
+    readonly stage: 'lineage';
+    readonly lineage: QueryLineage;
+    readonly partialResult: PartialExecuteResult;
+} | {
+    readonly stage: 'compiled';
+    readonly sqls: readonly ExecutedSql[];
+    readonly partialResult: PartialExecuteResult;
+} | {
+    readonly stage: 'executing';
+    readonly provider: CoreComputeProvider['kind'];
+    readonly partialResult: PartialExecuteResult;
+} | {
+    readonly stage: 'hydrating';
+    readonly partialResult: PartialExecuteResult;
+} | {
+    readonly stage: 'result';
+    readonly result: readonly DataRow[];
+    readonly partialResult: PartialExecuteResult;
+} | {
+    readonly stage: 'completed';
+    readonly durationMs: number;
+    readonly partialResult: PartialExecuteResult;
+} | {
+    readonly stage: 'failed';
+    readonly error: Error;
+    readonly partialResult: PartialExecuteResult;
+};
+export type ProgressCallback = (event: ExecuteProgressEvent) => void | Promise<void>;
+interface ExecuteBaseOptions {
+    readonly schemas: Readonly<Record<string, SemanticSchemaDraft>>;
+    readonly schemaMappings: SchemaMappingRegistry;
+    readonly semanticTypes?: SemanticTypeRegistry;
+    readonly operators?: OperatorRegistry;
+    /** Caller-owned capability plugins appended to the built-in plugin set for this execution. */
+    readonly plugins?: readonly SemanticDBPlugin[];
+    /** Locale for generated human-readable PredItem names. Defaults to zh-CN. */
+    readonly locale?: string;
+    /** Table, row, and column permissions for this execution. */
+    readonly permissions?: Permissions;
+    /** Legacy-compatible dynamically supplied composite metric definitions. */
+    readonly customFunctions?: CustomFunctions;
+    /** Third argument passed to mergeComponents/genMergeSQL callbacks. */
+    readonly customFunctionConfig?: Readonly<Record<string, unknown>>;
+    /** Optional caller-owned cache shared across executions. */
+    readonly cache?: QueryCacheExecutionOptions;
+    readonly onProgress?: ProgressCallback;
+    readonly signal?: AbortSignal;
+}
+export interface ExecuteOptions extends ExecuteBaseOptions {
+    /** Database connections addressable by SchemaMappingDefinition.connectionId. */
+    readonly connections: readonly DatabaseConnection[];
+}
+/** Internal execution seam used by executor tests after a provider has been resolved. */
+export interface InternalExecuteOptions extends ExecuteBaseOptions {
+    readonly provider: CoreComputeProvider;
+    /** Selected connection for public execution; omitted only by internal provider tests. */
+    readonly connectionId?: string;
+}
+export interface ExecuteSuccessResult {
+    readonly result: DataRow[];
+    /** Schema describing the computed result rows. */
+    readonly schema: ResolvedSemanticSchema;
+    readonly normedLogicform: LogicformType;
+    readonly sqls: readonly ExecutedSql[];
+    readonly lineage: QueryLineage;
+    readonly provider: CoreComputeProvider['kind'];
+}
+export interface ExecuteFailureResult {
+    readonly errorCode: '100';
+    readonly error: string;
+    readonly result: readonly [];
+    readonly schema?: ResolvedSemanticSchema;
+    readonly normedLogicform: LogicformType;
+    readonly sqls: readonly ExecutedSql[];
+    readonly provider?: CoreComputeProvider['kind'];
+    readonly lineage?: QueryLineage;
+}
+export type ExecuteResult = ExecuteSuccessResult | ExecuteFailureResult;
+export type ExecutedSqlType = 'computation' | 'semantic-resolution';
+export interface ExecutedSql {
+    /** Why this SQL participates in the LogicForm execution. */
+    readonly type: ExecutedSqlType;
+    /** Parameterized SQL used for provider execution and cache identity. */
+    readonly sql: string;
+    readonly parameters: SqlParameters;
+    /** Dialect-formatted diagnostic SQL. SemanticDB never executes this string. */
+    readonly displaySql: string;
+}
+export type PartialExecuteResult = Partial<ExecuteSuccessResult>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export declare const Logicform: Readonly<{
+    execute: (inputLogicform: import("./logicform-types").LogicformType, inputOptions: import(".").ExecuteOptions) => Promise<import(".").ExecuteResult>;
+    close: () => Promise<void>;
+    genComponents: (pred: import("./logicform-types").PredItemType, options: import(".").GenMetricComponentsOptions) => import(".").MetricComponentNode;
+}>;
+export { SemanticDBError } from './errors';
+export { builtinSemanticTypes, createSemanticTypeRegistry, resolveSchema, SemanticTypeRegistry, validateResolvedSchema, } from './semantic-types/index';
+export { builtinOperators, createOperatorRegistry, OperatorRegistry, } from './operators/index';
+export type { LegacySchemaPluginContext, SchemaMetadataPlugin, SemanticDBPlugin, } from './plugins/index';
+export { SchemaMappingRegistry, } from './schema-mappings/index';
+export type { AbsoluteDateValue, CompareOperator, CalendarDateValue, DateTimeValue, DateValue, ExpressionItemType, LogicformType, PeriodShiftTime, PredItemType, QueryLogicalOperand, RecursiveQueryType, RelationQueryType, QueryType, QueryValueType, QueryValueTypeWithCompareOperator, RelativeDateValue, RepresentationType, } from './logicform-types';
+export { CALENDAR_DATES_TABLE, CALENDAR_RELATIONS_TABLE, CALENDAR_SYSTEM_SCHEMA_IDS, calendarSystemSchemas, ProviderCalendarRelationStore, resolveCalendarPeriod, resolveCalendarPeriodFromStore, selectCalendarDates, } from './calendar/index';
+export type { CalendarAlignment, CalendarComparison, CalendarDateRow, CalendarRelation, CalendarRelationRow, ResolvedCalendarPeriod, } from './calendar/index';
+export type { CalendarRelationStore } from './calendar/index';
+export type { PrimalType, PropertySqlDefinition, ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeNormalizeContext, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, SemanticTypeResultContext, SemanticTypeResultProperty, TemporalSemantics, TimeGranularity, } from './semantic-types/index';
+export type { HierarchyDefinition, HierarchyLevelDefinition, ResolvedHierarchyDefinition, } from './plugins/hierarchy/index';
+export type { DataRow, SqlParameters, DatabaseConnection, } from './physical/index';
+export type { OperatorDefinition, OperatorDefaultNameContext, OperatorComponentContext, OperatorCteCalculation, OperatorCteComponent, OperatorCteSqlContext, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, } from './operators/index';
+export type { SchemaMappingDefinition, SchemaMappingPredDefinition, SchemaMappingPredMatch, SourceFreshnessPolicy, } from './schema-mappings/index';
+export type { QueryCache, QueryCacheExecutionOptions, QueryCacheIdentity, QueryCacheWriteOptions, } from './cache/index';
+export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, PartialExecuteResult, ProgressCallback, } from './executor/index';
+export type { ColumnPermissions, Permissions, SchemaPermissions, } from './permissions/index';
+export type { CustomFunctionColumnProperty, CustomFunctionDefinition, CustomFunctionHelpers, CustomFunctionSqlContext, CustomFunctions, GenComponents, GenComponentsContext, GenMergeSQL, GenMetricComponentsOptions, MergeComponents, MetricComponentNode, } from './custom-functions/index';
+export type { CreateLogicalPlanOptions, LogicalPlan, QueryLineage, } from './planner/index';
+export { PlannerSemanticRegistry, createPlannerSemanticRegistry, } from './planner/index';
+export type { PlannerSemanticResolution, PlannerSemanticQueryContext, PlannerSemanticRule, PlannerSemanticRuleContext, } from './planner/index';

package/dist/index.js

@@ -0,0 +1 @@
+import{execute as e}from"./executor/execute.js";import{closeConnections as r}from"./executor/connection-registry.js";import{genMetricComponents as o}from"./custom-functions/custom-functions.js";import{SemanticDBError as c}from"./errors.js";import{createSemanticTypeRegistry as f}from"./semantic-types/index.js";import{builtinOperators as l,createOperatorRegistry as x}from"./operators/index.js";import{SchemaMappingRegistry as g}from"./schema-mappings/registry.js";import{CALENDAR_DATES_TABLE as A,CALENDAR_RELATIONS_TABLE as C,CALENDAR_SYSTEM_SCHEMA_IDS as d}from"./calendar/constants.js";import{resolveCalendarPeriod as T,resolveCalendarPeriodFromStore as D,selectCalendarDates as L}from"./calendar/resolver.js";import{ProviderCalendarRelationStore as v}from"./calendar/provider-relation-store.js";import{calendarSystemSchemas as P}from"./calendar/system-schemas.js";import{PlannerSemanticRegistry as M}from"./planner/semantics/registry.js";import{createPlannerSemanticRegistry as b}from"./planner/semantics/registry-defaults.js";import{OperatorRegistry as B}from"./operators/registry.js";import{SemanticTypeRegistry as j}from"./semantic-types/registry.js";import{builtinSemanticTypes as F}from"./semantic-types/builtins/index.js";import{resolveSchema as Y}from"./semantic-types/resolve-schema.js";import{validateResolvedSchema as q}from"./semantic-types/validate-resolved-schema.js";const t=Object.freeze({execute:e,close:r,genComponents:o});export{A as CALENDAR_DATES_TABLE,C as CALENDAR_RELATIONS_TABLE,d as CALENDAR_SYSTEM_SCHEMA_IDS,t as Logicform,B as OperatorRegistry,M as PlannerSemanticRegistry,v as ProviderCalendarRelationStore,g as SchemaMappingRegistry,c as SemanticDBError,j as SemanticTypeRegistry,l as builtinOperators,F as builtinSemanticTypes,P as calendarSystemSchemas,x as createOperatorRegistry,b as createPlannerSemanticRegistry,f as createSemanticTypeRegistry,T as resolveCalendarPeriod,D as resolveCalendarPeriodFromStore,Y as resolveSchema,L as selectCalendarDates,q as validateResolvedSchema};

package/dist/logicform-types.d.ts

@@ -0,0 +1,125 @@
+import type { TimeGranularity } from './semantic-types/index';
+export type RepresentationType = 'value' | 'table' | 'pie' | 'bar' | 'column' | 'stackedColumn' | 'line' | 'scatter' | 'area' | 'bubble' | 'funnel' | 'guage' | 'heatmap' | 'histogram' | 'pareto' | 'radar' | 'treemap' | 'wordCloud' | 'map' | 'entity' | 'report' | 'text' | 'videos' | 'images';
+/** A concrete timestamp accepted by a LogicForm query. */
+export type DateTimeValue = `${number}-${number}-${number} ${number}:${number}:${number}`;
+/** A relative period resolved from the execution clock. */
+export interface RelativeDateValue {
+    readonly granularity: TimeGranularity;
+    readonly offset: number;
+}
+/** Calendar components identifying an absolute period. */
+export interface AbsoluteDateValue {
+    readonly year?: number;
+    readonly quarter?: number;
+    readonly month?: number;
+    readonly week?: number;
+    readonly day?: number;
+    readonly hour?: number;
+    readonly minute?: number;
+    readonly second?: number;
+    readonly period?: 'am' | 'pm';
+}
+/** A business-calendar period resolved to natural days before planning. */
+export interface CalendarDateValue {
+    readonly calendar: string;
+    readonly key?: string;
+    readonly year?: number;
+    readonly quarter?: number;
+    readonly month?: number;
+    readonly week?: number;
+    readonly day?: number;
+    readonly relativeDay?: number | readonly number[];
+}
+/** Period reference used by operators such as `$periodShift`. */
+export type PeriodShiftTime = RelativeDateValue | AbsoluteDateValue;
+/** A date value before semantic-type normalization. */
+export type DateValue = string | RelativeDateValue | AbsoluteDateValue | CalendarDateValue;
+export type CompareOperator = '$eq' | '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$nin' | '$exists' | '$regex' | '$contains' | '$recursive' | '$and' | '$or';
+export interface RecursiveQueryType {
+    readonly schema?: string;
+    readonly root?: QueryValueType;
+    readonly roots?: QueryValueType[];
+    readonly includeSelf?: boolean;
+    readonly idProperty?: string;
+    readonly parentProperty?: string;
+}
+export type QueryValueType = null | string | number | boolean | DateValue | RelationQueryType | LogicformType | string[] | number[] | boolean[] | DateValue[] | RelationQueryType[] | LogicformType[];
+/** A query scoped through an object relation. Version is inherited from the parent LogicForm. */
+export interface RelationQueryType {
+    readonly version?: string;
+    readonly schema: string;
+    readonly query: QueryType;
+    /** Stable entity identity. `placeholder` preserves context without adding an ID filter. */
+    readonly entity_id?: string;
+}
+export type QueryLogicalOperand = QueryValueType | QueryValueTypeWithCompareOperator;
+export type QueryValueTypeWithCompareOperator = Partial<{
+    $eq: QueryValueType;
+    $gt: QueryValueType;
+    $gte: QueryValueType;
+    $lt: QueryValueType;
+    $lte: QueryValueType;
+    $ne: QueryValueType;
+    $in: QueryValueType;
+    $nin: QueryValueType;
+    $exists: QueryValueType;
+    $regex: QueryValueType;
+    $contains: QueryValueType;
+    args?: {
+        readonly options?: string;
+    };
+    $recursive: QueryValueType | RecursiveQueryType;
+    $and: QueryLogicalOperand[];
+    $or: QueryLogicalOperand[];
+}> & {
+    readonly schema?: never;
+};
+export type QueryType = Record<string, QueryValueType | QueryValueTypeWithCompareOperator | QueryType[] | undefined> & {
+    readonly $and?: QueryType[];
+    readonly $or?: QueryType[];
+};
+export interface ExpressionItemType {
+    operator?: string;
+    pred?: string | ExpressionItemType;
+    /** Structural operands for multi-input operators. Operator options remain in `args`. */
+    components?: ExpressionItemType[];
+    name?: string;
+    schema?: string;
+    args?: Record<string, unknown>;
+}
+export interface PredItemType extends ExpressionItemType {
+    pred?: string | PredItemType;
+    components?: PredItemType[];
+    query?: QueryType;
+}
+export type LogicformOutputTypeValue = 'url' | 'data' | 'export' | 'sql' | 'sqlComponents';
+export interface LogicformOutputType {
+    type: LogicformOutputTypeValue;
+    filename?: string;
+}
+export interface LogicformType {
+    /** LogicForm protocol version. This SDK supports version 2.0 and later. */
+    version: string;
+    /** Required for a physical leaf. Derived and composed nodes inherit their field space. */
+    schema?: string;
+    /** Complete child LogicForms whose result columns are combined by their shared row identity. */
+    logicforms?: LogicformType[];
+    query?: QueryType;
+    preds?: PredItemType[];
+    groupby?: PredItemType[];
+    sort?: Record<string, 1 | -1>;
+    having?: QueryType;
+    output?: LogicformOutputType;
+    limit?: number;
+    limitBy?: number;
+    page?: number;
+    representation?: RepresentationType;
+    /** Stable entity identity. `placeholder` preserves context without adding an ID filter. */
+    entity_id?: string;
+    from?: LogicformType;
+    currency?: string;
+}
+export declare const isLogicform: (value: unknown) => value is LogicformType;
+export declare const isComposedLogicform: (value: LogicformType) => value is LogicformType & {
+    readonly logicforms: LogicformType[];
+};

package/dist/logicform-types.js

@@ -0,0 +1 @@
+const r=o=>typeof o=="object"&&o!==null&&!Array.isArray(o)&&typeof o.version=="string"&&(typeof o.schema=="string"||Array.isArray(o.logicforms)||typeof o.from=="object"),s=o=>Array.isArray(o.logicforms);export{s as isComposedLogicform,r as isLogicform};

package/dist/normalizer/core.d.ts

@@ -0,0 +1,19 @@
+import type { LogicformType } from '../logicform-types';
+import type { OperatorRegistry } from '../operators/index';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeRegistry } from '../semantic-types/index';
+import type { SemanticDBPlugin } from '../plugins/index';
+export interface NormalizeLogicformOptions {
+    readonly semanticTypes: SemanticTypeRegistry;
+    readonly operators?: OperatorRegistry;
+    readonly plugins?: readonly SemanticDBPlugin[];
+    /** Locale used for generated human-readable PredItem names. Defaults to zh-CN. */
+    readonly locale?: string;
+    readonly now?: Date;
+    readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
+    readonly requestLatestDataDate?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => Promise<Date | undefined>;
+    readonly resolveFromSchema?: (normalizedFrom: LogicformType, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
+    readonly canProjectProperty?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => boolean;
+    /** Internal recursion hook installed by normalizeLogicform. */
+    readonly normalizeNestedLogicform?: (logicform: LogicformType) => Promise<LogicformType>;
+}
+export declare const resolveLogicformSchema: (logicform: LogicformType, currentSchema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => ResolvedSemanticSchema;

package/dist/normalizer/core.js

@@ -0,0 +1 @@
+import{SemanticDBError as t}from"../errors.js";const h=(e,s,a)=>{if(!e.schema||e.schema===s.id)return s;const r=a.resolveSchema?.(e.schema);if(!r)throw new t("SCHEMA_RESOLVER_REQUIRED",`Cannot normalize nested LogicForm schema without a schema resolver: ${e.schema}`,{schemaId:e.schema});return r};export{h as resolveLogicformSchema};

package/dist/normalizer/default-pred-name.d.ts

@@ -0,0 +1,6 @@
+import type { PredItemType } from '../logicform-types';
+import type { OperatorRegistry } from '../operators/index';
+export interface DefaultPredNameOptions {
+    readonly locale?: string;
+}
+export declare const defaultPredName: (pred: PredItemType, operators: OperatorRegistry, options?: DefaultPredNameOptions) => string;

package/dist/normalizer/default-pred-name.js

@@ -0,0 +1 @@
+import{SemanticDBError as N}from"../errors.js";import{predQueryName as g}from"./pred-query-name.js";const i=(e,n,o={})=>{if(e.name!==void 0){if(typeof e.name!="string"||e.name.length===0)throw new N("INVALID_PRED_NAME","PredItem name must be a non-empty string");return e.name}const r=o.locale??"zh-CN",a=r.toLowerCase().startsWith("en"),m=typeof e.pred=="string"?e.pred:e.pred?i(e.pred,n,o):void 0,s=e.components?.map(c=>i(c,n,o))??[],f=m??(s.length>0?s.join(a?", ":"\u3001"):a?"rows":"\u6570\u636E\u884C"),t=e.operator?n.get(e.operator).defaultName({operandName:f,...m?{inputName:m}:{},componentNames:s,args:e.args??{},locale:r}):f;if(typeof t!="string"||t.length===0)throw new N("INVALID_PRED_NAME",`Operator defaultName must return a non-empty name: ${e.operator}`,{operator:e.operator});if(!e.query)return t;const u=g(e.query,r);return u?a?`${t} where ${u}`:`${u}\u7684${t}`:t};export{i as defaultPredName};

package/dist/normalizer/entity-id.d.ts

@@ -0,0 +1,4 @@
+import type { QueryType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { SemanticDBPlugin } from '../plugins/index';
+export declare const applyEntityIdQuery: (query: QueryType | undefined, entityId: unknown, schema: ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[]) => QueryType | undefined;

package/dist/normalizer/entity-id.js

@@ -0,0 +1 @@
+import{SemanticDBError as s}from"../errors.js";import{isConcreteEntityId as p,resolveEntityFilterProperty as a}from"../schema/entity-identity.js";const i=(e,t)=>Object.entries(e).some(([n,o])=>t.has(n)?!0:n!=="$and"&&n!=="$or"||!Array.isArray(o)?!1:o.some(r=>typeof r=="object"&&r!==null&&!Array.isArray(r)&&i(r,t))),f=(e,t,n,o=[])=>{if(t===void 0||t==="placeholder")return e;if(!p(t))throw new s("INVALID_ENTITY_ID","entity_id must be a non-empty string");const r=a(n,o);return e&&i(e,new Set([r.name,r.id]))?e:{[r.name]:t,...e??{}}};export{f as applyEntityIdQuery};

package/dist/normalizer/groupby.d.ts

@@ -0,0 +1,4 @@
+import type { LogicformType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { NormalizeLogicformOptions } from './core';
+export declare const normalizeGroupby: (groupby: LogicformType["groupby"], schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => Promise<NonNullable<LogicformType["groupby"]>>;

package/dist/normalizer/groupby.js

@@ -0,0 +1 @@
+import{normalizePreds as m}from"./preds.js";const i=(o,r,e)=>m(o??[],r,e);export{i as normalizeGroupby};

package/dist/normalizer/index.d.ts

@@ -0,0 +1,3 @@
+export { normalizeLogicform } from './normalize-logicform';
+export { defaultPredName } from './default-pred-name';
+export { assertSupportedLogicformVersion } from './version';

package/dist/normalizer/normalize-logicform.d.ts

@@ -0,0 +1,4 @@
+import type { LogicformType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import { type NormalizeLogicformOptions } from './core';
+export declare const normalizeLogicform: (input: LogicformType, schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => Promise<LogicformType>;

package/dist/normalizer/normalize-logicform.js

@@ -0,0 +1 @@
+import{SemanticDBError as c}from"../errors.js";import{createOperatorRegistry as w}from"../operators/index.js";import{clone as g}from"../utils/clone.js";import{resolveLogicformSchema as d}from"./core.js";import{normalizeGroupby as I}from"./groupby.js";import{normalizePagination as S}from"./pagination.js";import{normalizePreds as z}from"./preds.js";import{normalizeQuery as L}from"./query.js";import{assertSupportedLogicformVersion as P}from"./version.js";import{applyEntityIdQuery as h}from"./entity-id.js";const b=async(e,m,r)=>{if(!e)return;const u=d(e,m,r);return f(e,u,r)},f=async(e,m,r)=>{if(r=r.operators?r:{...r,operators:w(r.plugins)},P(e),e.logicforms){const t=["schema","from","query","preds","groupby","having","limit","page","entity_id"].filter(s=>e[s]!==void 0);if(t.length>0)throw new c("INVALID_COMPOSED_LOGICFORM",`A composed LogicForm cannot define: ${t.join(", ")}`);if(e.logicforms.length<2)throw new c("COMPOSITION_REQUIRES_MULTIPLE_LOGICFORMS","logicforms must contain at least two LogicForms");if(e.limitBy!==void 0&&(!Number.isInteger(e.limitBy)||e.limitBy<=0))throw new c("INVALID_PAGINATION","limitBy must be a positive integer",{limitBy:e.limitBy});const l=g(e);return l.logicforms=await Promise.all(e.logicforms.map(s=>f(s,d(s,m,r),r))),l}if(e.output&&e.output.type!=="data"&&e.output.type!=="sql")throw new c("UNSUPPORTED_OUTPUT",`Output type is not supported: ${e.output.type}`);const o=g(e),a={...r,normalizeNestedLogicform:async t=>{const l=d(t,m,r);return f(t,l,r)}};S(o);const n=await b(o.from,m,a),i=n&&r.resolveFromSchema?r.resolveFromSchema(n,m):m,y=await L(h(o.query,o.entity_id,i,r.plugins),i,a),O=o.preds===void 0&&o.groupby===void 0?i.properties.filter(t=>r.canProjectProperty?.(i,t)??!0).map(t=>({pred:t.name,name:t.name})):o.preds;o.preds=await z(O,i,a);const p=await I(o.groupby,i,a);return p.length>0?o.groupby=p:delete o.groupby,n?o.from=n:delete o.from,y?o.query=y:delete o.query,o};export{f as normalizeLogicform};

package/dist/normalizer/pagination.d.ts

@@ -0,0 +1,2 @@
+import type { LogicformType } from '../logicform-types';
+export declare const normalizePagination: (logicform: LogicformType) => void;

package/dist/normalizer/pagination.js

@@ -0,0 +1 @@
+import{SemanticDBError as a}from"../errors.js";const n=(e,s)=>{throw new a("INVALID_PAGINATION",e,s)},u=e=>{"skip"in e&&n("skip has been removed; use the 1-based page field",{skip:e.skip});const s=e.groupby?.length??0;e.limitBy!==void 0&&((!Number.isInteger(e.limitBy)||e.limitBy<=0)&&n("limitBy must be a positive integer",{limitBy:e.limitBy}),s<2&&(e.limit=e.limitBy,delete e.limitBy));const{limit:i,page:t}=e;if(i===void 0){t!==void 0&&n("page requires limit",{page:t});return}if((!Number.isFinite(i)||i<0&&i!==-1||i>1&&!Number.isInteger(i))&&n("limit must be -1, a non-negative integer, or a ratio between 0 and 1",{limit:i}),i===-1){t!==void 0&&n("page cannot be used with unlimited results",{limit:i,page:t}),delete e.limit;return}t!==void 0&&(!Number.isInteger(t)||t<1)&&n("page must be a positive integer starting from 1",{page:t}),e.page=t??1};export{u as normalizePagination};

package/dist/normalizer/pred-query-name.d.ts

@@ -0,0 +1 @@
+export declare const predQueryName: (query: Readonly<Record<string, unknown>>, locale?: string) => string;

package/dist/normalizer/pred-query-name.js

@@ -0,0 +1 @@
+const f=t=>typeof t=="object"&&t!==null&&!Array.isArray(t),y={year:"\u5E74",quarter:"\u5B63\u5EA6",month:"\u6708",week:"\u5468",day:"\u65E5",hour:"\u65F6",minute:"\u5206",second:"\u79D2"},$=(t,r)=>{if(t===null)return r?"null":"\u7A7A\u503C";if(typeof t=="string"||typeof t=="number")return String(t);if(typeof t=="boolean")return r?String(t):t?"\u662F":"\u5426";if(Array.isArray(t))return t.map(n=>$(n,r)).join(r?", ":"\u3001");if(!f(t))return r?"the specified condition":"\u6307\u5B9A\u6761\u4EF6";if(Array.isArray(t.roots))return t.roots.map(n=>$(n,r)).join(r?", ":"\u3001");if(t.root!==void 0)return $(t.root,r);const e=["year","quarter","month","week","day","hour","minute","second"].filter(n=>t[n]!==void 0).map(n=>r?`${n} ${String(t[n])}`:`${String(t[n])}${y[n]??""}`);return e.length>0?e.join(r?", ":""):r?"the specified condition":"\u6307\u5B9A\u6761\u4EF6"},c=(t,r,e)=>t.filter(Boolean).join(e?r==="$and"?" and ":" or ":r==="$and"?"\u4E14":"\u6216"),d=(t,r,e,n)=>{const i=(n?{$eq:"is",$ne:"is not",$gt:"is greater than",$gte:"is at least",$lt:"is less than",$lte:"is at most",$in:"is one of",$nin:"is none of",$contains:"contains",$regex:"matches",$recursive:"is"}:{$eq:"\u4E3A",$ne:"\u4E0D\u4E3A",$gt:"\u5927\u4E8E",$gte:"\u5927\u4E8E\u7B49\u4E8E",$lt:"\u5C0F\u4E8E",$lte:"\u5C0F\u4E8E\u7B49\u4E8E",$in:"\u4E3A",$nin:"\u4E0D\u4E3A",$contains:"\u5305\u542B",$regex:"\u5339\u914D",$recursive:"\u5C5E\u4E8E"})[t];if(!i)return;const a=t==="$in"?n?"":"\u4E4B\u4E00":t==="$nin"?n?"":"\u4E2D\u7684\u4EFB\u4E00\u9879":t==="$recursive"?n?" or a descendant":"\u53CA\u5176\u4E0B\u7EA7":"";return n?`${r} ${i} ${e}${a}`:`${r}${i}${e}${a}`},u=(t,r,e)=>{if(!f(r)||Object.keys(r).every(o=>!o.startsWith("$")))return d("$eq",t,$(r,e),e)??"";const n=[];for(const[o,s]of Object.entries(r))if((o==="$and"||o==="$or")&&Array.isArray(s))n.push(c(s.map(i=>u(t,i,e)),o,e));else if(o==="$exists")n.push(e?`${t} ${s?"exists":"does not exist"}`:`${s?"\u6709":"\u65E0"}${t}`);else if(o!=="args"){const i=o==="$regex"&&f(s)?$(s.pattern,e):$(s,e),a=d(o,t,i,e);a&&n.push(a)}return c(n,"$and",e)},m=(t,r="zh-CN")=>{const e=r.toLowerCase().startsWith("en"),n=[];for(const[o,s]of Object.entries(t))(o==="$and"||o==="$or")&&Array.isArray(s)?n.push(c(s.map(i=>f(i)?m(i,r):""),o,e)):s!==void 0&&n.push(u(o,s,e));return c(n,"$and",e)};export{m as predQueryName};

package/dist/normalizer/preds.d.ts

@@ -0,0 +1,4 @@
+import type { PredItemType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { NormalizeLogicformOptions } from './core';
+export declare const normalizePreds: (preds: readonly PredItemType[] | undefined, schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => Promise<PredItemType[]>;

package/dist/normalizer/preds.js

@@ -0,0 +1 @@
+import{SemanticDBError as t}from"../errors.js";import{resolvePropertyPath as P}from"../schema/resolve-property-path.js";import{defaultPredName as d}from"./default-pred-name.js";import{normalizeQuery as y}from"./query.js";const w=e=>{if(typeof e!="object"||e===null||Array.isArray(e))return!1;const o=Object.getPrototypeOf(e);return o===Object.prototype||o===null},l=async(e,o,n)=>{const a=n.operators,i={...n.locale?{locale:n.locale}:{}};if(!a)throw new Error("Normalizer operator registry is not initialized");if(e.name!==void 0&&(typeof e.name!="string"||e.name.length===0))throw new t("INVALID_PRED_NAME","PredItem name must be a non-empty string");if(e.args!==void 0&&!w(e.args))throw new t("INVALID_OPERATOR_ARGS","Pred args must be a plain object");const m=e.schema===void 0||e.schema===o.id?o:n.resolveSchema?.(e.schema);if(!m)throw new t("SCHEMA_RESOLVER_REQUIRED",`Cross-Schema pred requires Schema ${e.schema}`);if(e.schema!==void 0&&e.schema!==o.id)throw new t("CROSS_SCHEMA_PRED_UNSUPPORTED","Cross-Schema pred.schema is not supported; use a composed LogicForm with logicforms",{sourceSchemaId:o.id,targetSchemaId:e.schema});const f=await y(e.query,m,n);if(e.pred!==void 0&&e.components!==void 0)throw new t("AMBIGUOUS_OPERATOR_INPUT","A PredItem cannot define both pred and components");if(e.components!==void 0&&!Array.isArray(e.components))throw new t("INVALID_OPERATOR_COMPONENTS","Pred components must be an array");const p=e.components?await Promise.all(e.components.map(r=>l(r,m,n))):void 0,s={...e,...f?{query:f}:{},...p?{components:p}:{}},c=r=>r.operator?a.get(r.operator).normalizePred?.({pred:r,schema:m})??r:r;if(typeof e.pred=="string"){const r=P(m,e.pred,n.resolveSchema),u={...s,pred:r.canonicalName},h={...s,pred:r.canonicalId};return c({...h,name:h.name??d(u,a,i)})}if(e.pred&&typeof e.pred=="object"&&!Array.isArray(e.pred)){const r={...s,pred:await l(e.pred,m,n)};return c({...r,name:r.name??d(r,a,i)})}if(e.pred!==void 0)throw new t("UNSUPPORTED_PRED","A pred must be a property name or nested pred");return c({...s,name:s.name??d(s,a,i)})},A=(e,o,n)=>Promise.all((e??[]).map(a=>l(a,o,n)));export{A as normalizePreds};

package/dist/normalizer/query.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { LogicformType } from '../logicform-types';
+import type { NormalizeLogicformOptions } from './core';
+export declare const normalizeQueryObject: (query: Readonly<Record<string, unknown>>, schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => Promise<Readonly<Record<string, unknown>>>;
+export declare const normalizeQuery: (query: LogicformType["query"], schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => Promise<LogicformType["query"]>;

package/dist/normalizer/query.js

@@ -0,0 +1 @@
+import{SemanticDBError as f}from"../errors.js";import{resolvePropertyPath as _}from"../schema/resolve-property-path.js";import{normalizePrimalQuery as L}from"../semantic-types/primal-types/index.js";import{isLogicform as h}from"../logicform-types.js";import{clone as $}from"../utils/clone.js";import{assertSupportedLogicformVersion as b}from"./version.js";import{applyEntityIdQuery as O}from"./entity-id.js";const I=e=>typeof e=="object"&&e!==null&&!Array.isArray(e)&&typeof e.schema=="string"&&typeof e.query=="object"&&e.query!==null&&!Array.isArray(e.query),N=e=>{if(!h(e))return!1;const o=e;return o.groupby!==void 0||o.preds!==void 0||o.from!==void 0||o.logicforms!==void 0||o.having!==void 0||o.sort!==void 0||o.limit!==void 0||o.limitBy!==void 0||o.page!==void 0},R=async(e,o)=>{if(h(e)){if(!o.normalizeNestedLogicform)throw new f("LOGICFORM_NORMALIZER_UNAVAILABLE","Nested query LogicForm must be normalized through normalizeLogicform");return o.normalizeNestedLogicform(e)}return Array.isArray(e)?Promise.all(e.map(r=>R(r,o))):typeof e!="object"||e===null||e instanceof Date?e:Object.fromEntries(await Promise.all(Object.entries(e).map(async([r,s])=>[r,await R(s,o)])))},A=(e,o)=>Object.fromEntries(Object.entries(e).map(([r,s])=>(r==="$and"||r==="$or")&&Array.isArray(s)?[r,s.map(n=>A(n,o))]:[`${o}_${r}`,s])),S=e=>{if(typeof e!="object"||e===null||Array.isArray(e))return e;const o=Object.entries(e),[r]=o;return o.length===1&&r?.[0]==="$eq"?r[1]:e},w=async(e,o,r,s)=>{const n=a=>{if(Array.isArray(a)){a.forEach(n);return}if(typeof a!="object"||a===null||h(a))return;const l=a;if("$options"in l)throw new f("UNSUPPORTED_QUERY_OPERATOR","$options is a LogicForm 1.x field; use args.options in LogicForm 2.0");Object.values(l).forEach(n)};n(e);const t=s.semanticTypes.get(r.type),i={schema:o,property:r,now:s.now??new Date,requestLatestDataDate:()=>Promise.resolve(s.requestLatestDataDate?.(o,r))},y=await L($(e),i),d=t.normalizeQuery?t.normalizeQuery(y,i):y;if(r.comparable){const a=new Set(r.comparable.values),l=(c,p)=>{if(!(h(c)||c===null)){if(Array.isArray(c)){c.forEach(m=>l(m,p));return}if(typeof c=="object"){Object.entries(c).forEach(([m,u])=>{["args","$exists","$regex","$contains"].includes(m)||l(u,m)});return}if(!(p&&["args","$exists","$regex","$contains"].includes(p))&&(typeof c!="string"||!a.has(c)))throw new f("COMPARABLE_VALUE_NOT_FOUND",`Comparable category ${r.name} does not contain value: ${JSON.stringify(c)}`,{property:r.name,value:c})}};l(d)}return d},P=async(e,o,r,s)=>{const n=typeof e=="object"&&e!==null&&!Array.isArray(e)?e:{root:e},t=typeof n.schema=="string"?n.schema:r.ref??o.id,i=t===o.id?o:s.resolveSchema?.(t);if(!i)throw new f("SCHEMA_RESOLVER_REQUIRED",`$recursive requires Schema ${t}`);const y=n.idProperty??n.id_property,d=i.properties.filter(({type:u})=>u==="ID"),a=y===void 0?d.length===1?d[0]:void 0:i.properties.find(({id:u,name:g})=>u===y||g===y);if(!a||y===void 0&&d.length!==1)throw new f("RECURSIVE_ID_PROPERTY_REQUIRED",`$recursive Schema ${t} must have exactly one ID property or idProperty`);const l=Array.isArray(n.roots),c=l?n.roots:n.root===void 0?[]:[n.root];if(!l&&c.length===0||c.some(u=>u===void 0))throw new f("RECURSIVE_ROOT_REQUIRED","$recursive requires root or roots");const p=await Promise.all(c.map(u=>w(u,i,a,s))),m=n.parentProperty??n.parent_property??i.parentProperty??"pid";if(typeof m!="string"||m.length===0)throw new f("RECURSIVE_PARENT_PROPERTY_REQUIRED","$recursive parentProperty must be a string");if(n.includeSelf!==void 0&&typeof n.includeSelf!="boolean"||n.include_self!==void 0&&typeof n.include_self!="boolean")throw new f("INVALID_RECURSIVE_QUERY","$recursive includeSelf must be boolean");return{schema:t,roots:p,includeSelf:n.includeSelf??n.include_self??!0,idProperty:a.name,parentProperty:m}},E=async(e,o,r)=>{const s={};for(const[n,t]of Object.entries(e)){if(n==="$and"||n==="$or"){if(!Array.isArray(t))throw new f("INVALID_QUERY_VALUE",`${n} requires an array`);s[n]=await Promise.all(t.map(async a=>{if(typeof a!="object"||a===null||Array.isArray(a))throw new f("INVALID_QUERY_VALUE",`${n} items must be query objects`);return E(a,o,r)}));continue}const i=_(o,n,r.resolveSchema);if(N(t)&&i.property.primal_type==="object"&&i.property.ref){if(t.schema!==i.property.ref)throw new f("RELATION_SCHEMA_MISMATCH",`Relation ${i.canonicalName} references ${i.property.ref}, not ${t.schema??"undefined"}`);if(!r.normalizeNestedLogicform)throw new f("LOGICFORM_NORMALIZER_UNAVAILABLE","Nested query LogicForm must be normalized through normalizeLogicform");const a=await r.normalizeNestedLogicform(t);s[i.canonicalName]={$in:a};continue}if(I(t)){if(t.version!==void 0&&b(t),i.property.primal_type!=="object"||!i.property.ref)throw new f("INVALID_RELATION_QUERY",`Nested LogicForm query requires an object property: ${i.canonicalName}`);if(t.schema!==i.property.ref)throw new f("RELATION_SCHEMA_MISMATCH",`Relation ${i.canonicalName} references ${i.property.ref}, not ${t.schema}`);const a=r.resolveSchema?.(t.schema);if(!a)throw new f("SCHEMA_RESOLVER_REQUIRED",`Nested relation query requires Schema ${t.schema}`);const l=O(t.query,t.entity_id,a,r.plugins),c=await E(l,a,r);Object.assign(s,A(c,i.canonicalName));continue}if(typeof t=="object"&&t!==null&&!Array.isArray(t)&&Object.prototype.hasOwnProperty.call(t,"$recursive")){const a=t;if(Object.keys(a).filter(c=>c!=="$recursive").length>0)throw new f("INVALID_RECURSIVE_QUERY","$recursive cannot be combined with other field operators");s[i.canonicalName]={$recursive:await P(a.$recursive,i.schema,i.property,r)};continue}const y=await R(t,r),d=await w(y,i.schema,i.property,r);s[i.canonicalName]=S(d)}return s},j=async(e,o,r)=>{if(e)return E(e,o,r)};export{j as normalizeQuery,E as normalizeQueryObject};

package/dist/normalizer/version.d.ts

@@ -0,0 +1,3 @@
+export declare const assertSupportedLogicformVersion: (logicform: {
+    readonly version?: unknown;
+}) => void;

package/dist/normalizer/version.js

@@ -0,0 +1 @@
+import{SemanticDBError as i}from"../errors.js";const s=/^(\d+)\.(\d+)(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/,u=r=>{if(typeof r!="string")return!1;const e=s.exec(r);if(!e)return!1;const n=Number(e[1]),t=Number(e[2]),o=Number(e[3]??0);return n!==2?n>2:t>0||o>0?!0:e[4]===void 0},c=r=>{if(!u(r.version))throw new i("UNSUPPORTED_LOGICFORM_VERSION",`This library only supports LogicForm version 2.0 or later; received ${JSON.stringify(r.version)}`,{minimumVersion:"2.0",receivedVersion:r.version})};export{c as assertSupportedLogicformVersion};

package/dist/operators/builtins/abs.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const absOperator: OperatorDefinition;

package/dist/operators/builtins/abs.js

@@ -0,0 +1 @@
+import{SemanticDBError as t}from"../../errors.js";const a={name:"$abs",defaultName:({operandName:r,locale:e})=>e.toLowerCase().startsWith("en")?`Absolute ${r}`:`${r}\u7EDD\u5BF9\u503C`,kind:"scalar",toSQL({expression:r}){if(!r)throw new t("PRED_PROPERTY_REQUIRED","$abs requires a pred");return`ABS(${r})`},getOutputProperty({name:r,inputProperty:e}){if(!e)throw new t("PRED_PROPERTY_REQUIRED","$abs requires a pred");return{...e,name:r,isArray:!1}}};export{a as absOperator};

package/dist/operators/builtins/accumulate.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const accumulateOperator: OperatorDefinition;

package/dist/operators/builtins/accumulate.js

@@ -0,0 +1 @@
+import m from"dayjs";import T from"dayjs/plugin/isoWeek.js";import L from"dayjs/plugin/quarterOfYear.js";import{SemanticDBError as u}from"../../errors.js";m.extend(T),m.extend(L);const N=new Set(["year","quarter","month","week"]),A=e=>e.format("YYYY-MM-DD HH:mm:ss"),g=(e,r)=>e.operator&&r(e.operator).kind==="aggregate"?!0:(typeof e.pred=="object"?g(e.pred,r):!1)||(e.components?.some(t=>g(t,r))??!1),y=(e,r,t)=>{if(e.kind==="window"||e.kind==="cumulative")throw new u("ACCUMULATE_WINDOW_UNSUPPORTED","$accumulate cannot contain another window expression");if(e.kind==="ordinal-decode")return{...e,input:y(e.input,r,t)};if(e.kind==="ordinal-encode")return{kind:"cumulative",function:"sum",input:e,...t};if(e.kind!=="operator")return{kind:"cumulative",function:"sum",input:e,...t};const c=r.getOperator(e.operator);if(c.kind==="component")throw new u("ACCUMULATE_OPERATOR_UNSUPPORTED",`$accumulate cannot contain component operator ${e.operator}`);if(c.kind==="aggregate"){if(e.operator==="$avg"){const i={...e,operator:"$sum"},p={...e,operator:"$count"};return{kind:"operator",operator:"$divide",args:{},components:[{kind:"cumulative",function:"sum",input:i,...t},{kind:"cumulative",function:"sum",input:p,...t}]}}const n={$sum:"sum",$count:"sum",$min:"min",$max:"max"}[e.operator];if(!n)throw new u("ACCUMULATE_OPERATOR_UNSUPPORTED",`Aggregate operator ${e.operator} does not declare cumulative semantics`);return{kind:"cumulative",function:n,input:e,...t}}if(c.kind!=="scalar")throw new u("ACCUMULATE_OPERATOR_UNSUPPORTED",`$accumulate cannot contain ${e.operator}`);return{...e,...e.input?{input:y(e.input,r,t)}:{},...e.components?{components:e.components.map(o=>y(o,r,t))}:{}}},D=e=>{if(!e.input||e.components.length>0||e.pred.query)throw new u("INVALID_ACCUMULATE_INPUT","$accumulate requires exactly one nested pred and does not accept pred.query");if(e.inputProperty?.comparable&&e.input.kind!=="ordinal-decode")throw new u("ACCUMULATE_COMPARABLE_OPERATOR_REQUIRED","$accumulate over a comparable category requires an explicit $min or $max metric");const r=e.args.partitionBy??[],t=e.args.orderBy;if(!Array.isArray(r)||r.some(o=>typeof o!="string"))throw new u("INVALID_ACCUMULATE_ARGS","$accumulate partitionBy must be an array of groupby names");if(!Array.isArray(t)||t.length===0)throw new u("INVALID_ACCUMULATE_ARGS","$accumulate requires a non-empty args.orderBy array");const c=t.map(o=>{if(typeof o!="object"||o===null||Array.isArray(o))throw new u("INVALID_ACCUMULATE_ARGS","$accumulate orderBy items require pred and optional direction");const{pred:n,direction:i="asc",...p}=o;if(typeof n!="string"||i!=="asc"&&i!=="desc"||Object.keys(p).length>0)throw new u("INVALID_ACCUMULATE_ARGS","$accumulate orderBy items require only a string pred and asc/desc direction");return{expression:e.resolveKey(n),direction:i==="asc"?"ASC":"DESC"}});return y(e.input,e,{partitionBy:r.map(o=>e.resolveKey(String(o))),orderBy:c})},I=e=>{if(e.groupByNames.length===0)return;if(typeof e.pred.pred!="object"||!g(e.pred.pred,e.getOperator))throw new u("ACCUMULATE_AGGREGATE_REQUIRED","$accumulate over a grouped physical relation requires an aggregate expression");const r=e.pred.args?.partitionBy,t=e.pred.args?.orderBy;if(r!==void 0&&!Array.isArray(r)||!Array.isArray(t)||t.length===0||t.some(n=>typeof n!="object"||n===null||Array.isArray(n)||typeof n.pred!="string"||Object.keys(n).some(i=>i!=="pred"&&i!=="direction")||n.direction!==void 0&&n.direction!=="asc"&&n.direction!=="desc"))return;const c=[...r??[],...t.map(n=>n.pred)];if(c.some(n=>typeof n!="string"))return;const o=c.map(n=>e.resolveGroupName(String(n)));if(o.length!==e.groupByNames.length||new Set(o).size!==e.groupByNames.length||e.groupByNames.some(n=>!o.includes(n)))throw new u("INCOMPLETE_ACCUMULATE_DIMENSIONS","$accumulate partitionBy and orderBy must cover every groupby item exactly once",{expected:e.groupByNames,received:o})},P=(e,r,t)=>{if(e.from||e.logicforms||e.having)throw new u("ACCUMULATE_PERIOD_UNSUPPORTED","$accumulate args.period currently requires a physical LogicForm without from, logicforms, or having");if((e.preds?.length??0)!==r.length)throw new u("ACCUMULATE_PERIOD_UNSUPPORTED","$accumulate args.period cannot currently be mixed with non-period projections");const c=e.query&&Object.entries(e.query).find(([,a])=>{if(typeof a!="object"||a===null||Array.isArray(a))return!1;const s=a;return typeof s.$gte=="string"&&typeof s.$lte=="string"});if(!c)throw new u("ACCUMULATE_PERIOD_QUERY_REQUIRED","$accumulate args.period requires one bounded date query identifying the target period");const[o,n]=c,i=n,p=m(String(i.$gte)),f=m(String(i.$lte));if(!p.isValid()||!f.isValid())throw new u("ACCUMULATE_PERIOD_QUERY_REQUIRED","Target date range is invalid");const _=r.map(a=>{if(!a.name)throw new u("MISSING_PRED_NAME","$accumulate args.period requires normalized names");return a.name}),$=t==="week"?p.startOf("isoWeek"):p.startOf(t),w={...e.query,[o]:{...i,$gte:A($)}},E=new Set([...(e.groupby??[]).map(({name:a})=>a),...(e.preds??[]).map(({name:a})=>a)]),U=a=>{let s=a;for(;E.has(s);)s=`_${s}`;return E.add(s),s},d=U("__accumulate_period"),h=r.map((a,s)=>U(`__accumulate_metric_${s}`)),l=(e.groupby??[]).map(({name:a})=>String(a)),C=t==="year"||t==="quarter"?"month":"day",R={version:e.version,...e.schema?{schema:e.schema}:{},query:w,groupby:[...e.groupby??[],{operator:"$dateBucket",pred:o,args:{granularity:C},name:d}],preds:r.map((a,s)=>({...a.pred,name:h[s]??`__accumulate_metric_${s}`}))},O={version:e.version,from:R,preds:[...l.map(a=>({pred:a,name:a})),{pred:d,name:d},...r.map((a,s)=>({operator:"$accumulate",pred:h[s]??`__accumulate_metric_${s}`,args:{partitionBy:l,orderBy:[{pred:d,direction:"asc"}]},name:_[s]??`accumulate_${s}`}))]};return{version:e.version,from:O,query:{[d]:{$gte:A(p),$lte:A(f)}},preds:[...l.map(a=>({pred:a,name:a})),..._.map(a=>({pred:a,name:a}))],...e.sort?{sort:e.sort}:{},...e.limit!==void 0?{limit:e.limit}:{},...e.page!==void 0?{page:e.page}:{},...e.output?{output:e.output}:{},...e.representation?{representation:e.representation}:{}}},S={name:"$accumulate",defaultName:({operandName:e,locale:r})=>r.toLowerCase().startsWith("en")?`Cumulative ${e}`:`${e}\u7D2F\u8BA1\u503C`,kind:"logical",normalizePred({pred:e}){const r=e.args?.period;if(r!==void 0&&(typeof r!="string"||!N.has(r)))throw new u("INVALID_ACCUMULATE_ARGS","$accumulate args.period must be year, quarter, month, or week");if(r!==void 0&&(e.args?.partitionBy!==void 0||e.args?.orderBy!==void 0))throw new u("INVALID_ACCUMULATE_ARGS","$accumulate args.period cannot be combined with partitionBy or orderBy");return e},planExpression:D,validatePlan:I,rewriteLogicform({logicform:e,schema:r}){const t=(e.preds??[]).filter(i=>i.operator==="$accumulate"&&i.args?.period!==void 0);if(t.length===0)return;const c=t[0]?.args?.period;if(t.some(i=>i.args?.period!==c))throw new u("ACCUMULATE_PERIOD_UNSUPPORTED","All $accumulate args.period projections in one LogicForm must use the same period");const o=new Set(Object.keys(e.query??{}));if(r.properties.filter(i=>i.primal_type==="date"&&o.has(i.name)).length!==1)throw new u("ACCUMULATE_PERIOD_QUERY_REQUIRED","$accumulate args.period requires exactly one queried date property");return P(e,t,c)},getOutputProperty({name:e,inputProperty:r}){return r?{...r,name:e,isArray:!1}:{name:e,type:"number",primal_type:"number",isArray:!1}}};export{S as accumulateOperator};

package/dist/operators/builtins/add.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const addOperator: OperatorDefinition;

package/dist/operators/builtins/add.js

@@ -0,0 +1 @@
+import{numericResult as s,requireExpressions as i}from"./arithmetic.js";const u={name:"$add",defaultName:({operandName:r,componentNames:t,locale:e})=>e.toLowerCase().startsWith("en")?t.length>0?t.join(" plus "):`Sum of ${r}`:t.length>0?t.join("\u52A0"):`${r}\u6C42\u548C`,kind:"scalar",requiresProperty:!1,toSQL(r){return`(${i("$add",r,2,Number.POSITIVE_INFINITY).join(" + ")})`},getOutputProperty({name:r,componentProperties:t}){const e=t?.[0];return e?{...e,name:r,isArray:!1}:s(r)}};export{u as addOperator};

package/dist/operators/builtins/arithmetic.d.ts

@@ -0,0 +1,3 @@
+import type { OperatorSqlContext, ResultProperty } from '../types';
+export declare const requireExpressions: (operator: string, context: OperatorSqlContext, minimum: number, maximum?: number) => readonly string[];
+export declare const numericResult: (name: string) => ResultProperty;

package/dist/operators/builtins/arithmetic.js

@@ -0,0 +1 @@
+import{SemanticDBError as o}from"../../errors.js";const p=(r,n,e,s=e)=>{const t=n.expressions??[];if(t.length<e||t.length>s)throw new o("INVALID_OPERATOR_COMPONENTS",`${r} requires ${e===s?String(e):`${e}-${s}`} components`);return t},c=r=>({name:r,type:"number",primal_type:"number",isArray:!1});export{c as numericResult,p as requireExpressions};

package/dist/operators/builtins/average-per-period.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const averagePerPeriodOperator: OperatorDefinition;

package/dist/operators/builtins/average-per-period.js

@@ -0,0 +1 @@
+import{SemanticDBError as m}from"../../errors.js";import{clone as s}from"../../utils/clone.js";import{combineQueries as g,collectPredQueries as P}from"./period-shift.js";import{requireTimestampProperty as f}from"./time-range.js";import{groupbyOutputName as l}from"../groupby.js";const $=new Set(["day","week","month","quarter","year"]),q={day:"\u65E5",week:"\u5468",month:"\u6708",quarter:"\u5B63\u5EA6",year:"\u5E74"},w=r=>{if(typeof r!="string"||!$.has(r))throw new m("INVALID_AVERAGE_PER_PERIOD_ARGS","$averagePerPeriod args.granularity must be day, week, month, quarter, or year");return r},u=r=>{const e=s(r);return delete e.having,delete e.sort,delete e.limit,delete e.page,e},i=r=>{const e=s(r);return delete e.query,e.pred&&typeof e.pred=="object"&&(e.pred=i(e.pred)),e.components&&(e.components=e.components.map(i)),e},h={name:"$averagePerPeriod",defaultName:({operandName:r,args:e,locale:o})=>o.toLowerCase().startsWith("en")?`Average ${r} per ${typeof e.granularity=="string"?e.granularity:"period"}`:`${r}${q[String(e.granularity)]??"\u5468\u671F"}\u5747\u503C`,kind:"component",createComponent({logicform:r,pred:e,schema:o}){if(!e.pred||typeof e.pred!="object"||Array.isArray(e.pred))throw new m("INVALID_AVERAGE_PER_PERIOD_INPUT","$averagePerPeriod pred must be a nested metric");const d=w(e.args?.granularity),c=f(o,"$averagePerPeriod"),y=i(e.pred),t=g([r.query,...P(e)]),n=u(r);n.preds=[{...y,name:"__average_per_period_numerator__"}],t&&(n.query=t);const a=u(r);a.preds=[{operator:"$countDistinct",pred:{operator:"$dateBucket",pred:c.name,args:{granularity:d},name:"__average_per_period_bucket__"},name:"__average_per_period_denominator__"}],t&&(a.query=t);const _=(r.groupby??[]).map(l);return{kind:"cte",components:[{name:"numerator",component:{kind:"query",logicform:n}},{name:"denominator",component:{kind:"query",logicform:a},joinKeys:_}],toSQL:({values:p})=>`${p.numerator} / NULLIF(${p.denominator}, 0)`}},getOutputProperty({name:r,inputProperty:e}){if(!e)throw new Error("$averagePerPeriod requires a nested metric");return{...e,name:r,isArray:!1}}};export{h as averagePerPeriodOperator};

package/dist/operators/builtins/avg.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const avgOperator: OperatorDefinition;

package/dist/operators/builtins/avg.js

@@ -0,0 +1 @@
+const o={name:"$avg",defaultName:({operandName:r,locale:e})=>e.toLowerCase().startsWith("en")?`Average ${r}`:`${r}\u5E73\u5747\u503C`,kind:"aggregate",toSQL(r){const{column:e,sql:t}=r;if(!e)throw new Error("$avg requires a column");return t.aggregateFunction("avg",e)},getOutputProperty({name:r,property:e,inputProperty:t}){const a=e??t;if(!a)throw new Error("$avg requires a property");return{name:r,type:a.type,primal_type:a.primal_type,isArray:!1}}};export{o as avgOperator};

package/dist/operators/builtins/case.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const caseOperator: OperatorDefinition;

package/dist/operators/builtins/case.js

@@ -0,0 +1 @@
+import{SemanticDBError as r}from"../../errors.js";const f=e=>{if(e.mode!=="auto")return;const n=e.buckets;if(!Number.isInteger(n)||n<2||n>100)throw new r("INVALID_CASE_ARGS","$case auto mode requires args.buckets to be an integer between 2 and 100");if(Object.hasOwn(e,"cases"))throw new r("INVALID_CASE_ARGS","$case auto mode cannot define args.cases");for(const t of["min","max"])if(e[t]!==void 0&&typeof e[t]!="number"||e[t]!==void 0&&!Number.isFinite(e[t]))throw new r("INVALID_CASE_ARGS",`$case auto mode ${t} must be finite number`);if(e.min===void 0!=(e.max===void 0))throw new r("INVALID_CASE_ARGS","$case auto mode requires both min and max");return n},E=e=>{if(!Array.isArray(e)||e.length===0)throw new r("INVALID_CASE_ARGS","$case requires a non-empty args.cases array");return e.map(n=>{if(typeof n!="object"||n===null||!("when"in n)||!("then"in n))throw new r("INVALID_CASE_ARGS","Each $case item requires when and then");const t=n;return{when:t.when,then:t.then}})},h={name:"$case",defaultName:({operandName:e,locale:n})=>n.toLowerCase().startsWith("en")?`${e} category`:`${e}\u5206\u7C7B`,kind:"scalar",toSQL({expression:e,args:n,sql:t}){if(!e)throw new r("PRED_PROPERTY_REQUIRED","$case requires a pred");const o=f(n);if(o!==void 0){const a=n.min===void 0?`MIN(${e}) OVER ()`:t.value(n.min),u=n.max===void 0?`MAX(${e}) OVER ()`:t.value(n.max),s=`(${u} - ${a})`,m=Array.from({length:o-1},(A,c)=>{const $=`${a} + ${s} * ${c+1} / ${o}`;return`WHEN ${e} < ${$} THEN ${t.value(c)}`});return`CASE WHEN ${a} = ${u} THEN ${t.value(0)} ${m.join(" ")} ELSE ${t.value(o-1)} END`}const i=E(n.cases).map(({when:a,then:u})=>`WHEN ${t.condition(e,a)} THEN ${t.value(u)}`),d=Object.hasOwn(n,"default")?` ELSE ${t.value(n.default)}`:"";return`CASE ${i.join(" ")}${d} END`},getOutputProperty({name:e}){return{name:e,type:"category",primal_type:"string",isArray:!1}}};export{h as caseOperator};

package/dist/operators/builtins/concat.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const concatOperator: OperatorDefinition;

package/dist/operators/builtins/concat.js

@@ -0,0 +1 @@
+import{requireExpressions as i}from"./arithmetic.js";const a={name:"$concat",defaultName:({operandName:r,componentNames:t,locale:e})=>e.toLowerCase().startsWith("en")?t.length>0?`Combined ${t.join(" and ")}`:`Combined ${r}`:t.length>0?`${t.join("\u4E0E")}\u62FC\u63A5\u503C`:`${r}\u62FC\u63A5\u503C`,kind:"scalar",requiresProperty:!1,toSQL(r){return r.sql.concat(i("$concat",r,1,Number.POSITIVE_INFINITY))},getOutputProperty({name:r}){return{name:r,type:"string",primal_type:"string",isArray:!1}}};export{a as concatOperator};

package/dist/operators/builtins/count-distinct.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const countDistinctOperator: OperatorDefinition;

package/dist/operators/builtins/count-distinct.js

@@ -0,0 +1 @@
+const e={name:"$countDistinct",defaultName:({operandName:t,locale:n})=>n.toLowerCase().startsWith("en")?`Distinct ${t} count`:`${t}\u53BB\u91CD\u8BA1\u6570`,kind:"aggregate",toSQL(t){const{column:n,sql:r}=t;if(!n)throw new Error("$countDistinct requires a column");return r.aggregateFunction("count",`DISTINCT ${n}`)},getOutputProperty({name:t}){return{name:t,type:"int",primal_type:"number",isArray:!1}}};export{e as countDistinctOperator};

package/dist/operators/builtins/count.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const countOperator: OperatorDefinition;

package/dist/operators/builtins/count.js

@@ -0,0 +1 @@
+const o={name:"$count",defaultName:({operandName:t,locale:r})=>r.toLowerCase().startsWith("en")?t==="rows"?"Row count":`${t} count`:t==="\u6570\u636E\u884C"?"\u884C\u6570":`${t}\u6570\u91CF`,kind:"aggregate",requiresProperty:!1,toSQL(t){const{column:r,sql:e}=t;return e.aggregateFunction("count",r)},getOutputProperty({name:t}){return{name:t,type:"int",primal_type:"number",isArray:!1}}};export{o as countOperator};

package/dist/operators/builtins/date-bucket.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const dateBucketOperator: OperatorDefinition;

package/dist/operators/builtins/date-bucket.js

@@ -0,0 +1 @@
+import{SemanticDBError as a}from"../../errors.js";const i=new Set(["hour","day","week","month","quarter","year"]),o={hour:"\u5C0F\u65F6",day:"\u65E5",week:"\u5468",month:"\u6708",quarter:"\u5B63\u5EA6",year:"\u5E74"},n=r=>{if(typeof r!="string"||!i.has(r))throw new a("INVALID_DATE_BUCKET_ARGS","$dateBucket args.granularity must be hour, day, week, month, quarter, or year");return r},y={name:"$dateBucket",defaultName:({operandName:r,args:t,locale:e})=>e.toLowerCase().startsWith("en")?`${r} by ${typeof t.granularity=="string"?t.granularity:"time"}`:`${r}\uFF08\u6309${o[String(t.granularity)]??"\u65F6\u95F4"}\uFF09`,kind:"scalar",toSQL({expression:r,args:t,sql:e}){if(!r)throw new Error("$dateBucket requires a date pred");return e.dateBucket(r,n(t.granularity))},getOutputProperty({name:r,inputProperty:t,args:e}){if(!t||t.primal_type!=="date")throw new a("DATE_BUCKET_DATE_REQUIRED","$dateBucket requires a date-valued pred");const u=n(e.granularity);return{...t,name:r,type:"date",primal_type:"date",isArray:!1,granularity:u}}};export{y as dateBucketOperator};

package/dist/operators/builtins/divide.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const divideOperator: OperatorDefinition;

package/dist/operators/builtins/divide.js

@@ -0,0 +1 @@
+import{numericResult as i,requireExpressions as d}from"./arithmetic.js";const u={name:"$divide",defaultName:({operandName:t,componentNames:r,locale:e})=>e.toLowerCase().startsWith("en")?r.length>=2?`${r[0]} divided by ${r[1]}`:`${t} ratio`:r.length>=2?`${r[0]}\u9664\u4EE5${r[1]}`:`${t}\u6BD4\u503C`,kind:"scalar",requiresProperty:!1,toSQL(t){const[r,e]=d("$divide",t,2);return`(${r} / NULLIF(${e}, 0))`},getOutputProperty({name:t}){return i(t)}};export{u as divideOperator};

package/dist/operators/builtins/index.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const builtinOperators: readonly OperatorDefinition[];

package/dist/operators/builtins/index.js

@@ -0,0 +1 @@
+import{accumulateOperator as r}from"./accumulate.js";import{absOperator as o}from"./abs.js";import{addOperator as t}from"./add.js";import{averagePerPeriodOperator as p}from"./average-per-period.js";import{avgOperator as m}from"./avg.js";import{caseOperator as e}from"./case.js";import{concatOperator as a}from"./concat.js";import{countOperator as i}from"./count.js";import{countDistinctOperator as f}from"./count-distinct.js";import{dateBucketOperator as O}from"./date-bucket.js";import{divideOperator as c}from"./divide.js";import{maxOperator as n}from"./max.js";import{minOperator as u}from"./min.js";import{multiplyOperator as d}from"./multiply.js";import{newlyOperator as s}from"./newly.js";import{periodBoundaryOperator as l}from"./period-boundary.js";import{periodDifferenceOperator as b}from"./period-difference.js";import{periodShiftOperator as g}from"./period-shift.js";import{periodGrowthOperator as h}from"./period-growth.js";import{sumOperator as v}from"./sum.js";import{subtractOperator as w}from"./subtract.js";import{shareOfTotalOperator as y}from"./share-of-total.js";import{substringOperator as k}from"./substring.js";import{sqlOperator as x}from"./sql.js";import{rankOperator as B}from"./rank.js";import{rowNumberOperator as D}from"./row-number.js";const P=Object.freeze([r,v,i,f,m,u,n,g,h,b,p,l,s,t,w,d,c,o,y,e,a,k,O,x,B,D]);export{P as builtinOperators};

package/dist/operators/builtins/max.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const maxOperator: OperatorDefinition;

package/dist/operators/builtins/max.js

@@ -0,0 +1 @@
+const o=r=>{if(!(!r.inputProperty?.comparable||!r.input))return{kind:"ordinal-decode",comparable:r.inputProperty.comparable,input:{kind:"operator",operator:"$max",args:r.args,...r.pred.query?{query:r.planQuery(r.pred.query)}:{},input:{kind:"ordinal-encode",input:r.input,comparable:r.inputProperty.comparable}}}},n={name:"$max",defaultName:({operandName:r,locale:a})=>a.toLowerCase().startsWith("en")?`Maximum ${r}`:`${r}\u6700\u5927\u503C`,kind:"aggregate",planExpression:o,toSQL(r){const{column:a,sql:p}=r;if(!a)throw new Error("$max requires a column");return p.aggregateFunction("max",a)},getOutputProperty({name:r,property:a,inputProperty:p}){const e=a??p;if(!e)throw new Error("$max requires a property");return{name:r,type:e.type,primal_type:e.primal_type,isArray:!1,...e.comparable?{comparable:e.comparable}:{}}}};export{n as maxOperator};

package/dist/operators/builtins/min.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const minOperator: OperatorDefinition;

package/dist/operators/builtins/min.js

@@ -0,0 +1 @@
+const n=r=>{if(!(!r.inputProperty?.comparable||!r.input))return{kind:"ordinal-decode",comparable:r.inputProperty.comparable,input:{kind:"operator",operator:"$min",args:r.args,...r.pred.query?{query:r.planQuery(r.pred.query)}:{},input:{kind:"ordinal-encode",input:r.input,comparable:r.inputProperty.comparable}}}},i={name:"$min",defaultName:({operandName:r,locale:e})=>e.toLowerCase().startsWith("en")?`Minimum ${r}`:`${r}\u6700\u5C0F\u503C`,kind:"aggregate",planExpression:n,toSQL(r){const{column:e,sql:p}=r;if(!e)throw new Error("$min requires a column");return p.aggregateFunction("min",e)},getOutputProperty({name:r,property:e,inputProperty:p}){const a=e??p;if(!a)throw new Error("$min requires a property");return{name:r,type:a.type,primal_type:a.primal_type,isArray:!1,...a.comparable?{comparable:a.comparable}:{}}}};export{i as minOperator};

package/dist/operators/builtins/multiply.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorDefinition } from '../types';
+export declare const multiplyOperator: OperatorDefinition;

package/dist/operators/builtins/multiply.js

@@ -0,0 +1 @@
+import{numericResult as i,requireExpressions as u}from"./arithmetic.js";const l={name:"$multiply",defaultName:({operandName:r,componentNames:t,locale:e})=>e.toLowerCase().startsWith("en")?t.length>0?t.join(" times "):`Product of ${r}`:t.length>0?t.join("\u4E58\u4EE5"):`${r}\u4E58\u79EF`,kind:"scalar",requiresProperty:!1,toSQL(r){return`(${u("$multiply",r,2,Number.POSITIVE_INFINITY).join(" * ")})`},getOutputProperty({name:r}){return i(r)}};export{l as multiplyOperator};