semanticdb-v2 2.0.0-alpha.1

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

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

package/dist/operators/builtins/newly.js

@@ -0,0 +1 @@
+import{SemanticDBError as s}from"../../errors.js";import{resolvePropertyPath as w}from"../../schema/resolve-property-path.js";import{clone as y}from"../../utils/clone.js";import{resolvePredTimeRange as l,withTimeCondition as f}from"./time-range.js";import{groupbyPropertyReference as _,groupbyOutputName as E}from"../groupby.js";const g=t=>{const e=y(t);return delete e.having,delete e.sort,delete e.limit,delete e.page,e},i=t=>{const e=y(t);return delete e.query,e.pred&&typeof e.pred=="object"&&(e.pred=i(e.pred)),e.components&&(e.components=e.components.map(i)),e},N={name:"$newly",defaultName:({operandName:t,locale:e})=>e.toLowerCase().startsWith("en")?`New ${t}`:`\u65B0\u589E${t}`,kind:"component",createComponent({logicform:t,pred:e,schema:m,resolveSchema:a}){if(!e.pred||typeof e.pred!="object"||Array.isArray(e.pred))throw new s("INVALID_NEWLY_INPUT","$newly pred must be a nested metric");if((t.groupby??[]).some(n=>{const o=_(n);return o?w(m,o,a).property.type==="timestamp":!1}))throw new s("NEWLY_TIME_GROUPBY_UNSUPPORTED","$newly does not support grouping by the timestamp property");const r=l(t.query,e,m,a,"$newly");if(r.start===void 0||r.end===void 0)throw new s("NEWLY_RANGE_REQUIRED","$newly requires both start and end timestamp bounds");const u=i(e.pred),d=(n,o)=>{const p=g(t);return p.query=f(r.queryWithoutTime,r.propertyName,{$lte:n}),p.preds=[{...u,name:o}],p},c=(t.groupby??[]).map(E);return{kind:"cte",components:[{name:"end",component:{kind:"query",logicform:d(r.end,"__newly_end__")}},{name:"start",component:{kind:"query",logicform:d(r.start,"__newly_start__")},joinKeys:c}],toSQL:({values:n})=>`${n.end} - COALESCE(${n.start}, 0)`}},getOutputProperty({name:t,inputProperty:e}){if(!e)throw new Error("$newly requires a nested metric");return{...e,name:t,isArray:!1}}};export{N as newlyOperator};

package/dist/operators/builtins/period-boundary.d.ts

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

package/dist/operators/builtins/period-boundary.js

@@ -0,0 +1 @@
+import{SemanticDBError as n}from"../../errors.js";import{clone as u}from"../../utils/clone.js";import{resolvePredTimeRange as c,withTimeCondition as _}from"./time-range.js";const l=r=>{const e=u(r);return delete e.having,delete e.sort,delete e.limit,delete e.page,e},s=r=>{const e=u(r);return delete e.query,e.pred&&typeof e.pred=="object"&&(e.pred=s(e.pred)),e.components&&(e.components=e.components.map(s)),e},b={name:"$periodBoundary",defaultName:({operandName:r,args:e,locale:a})=>a.toLowerCase().startsWith("en")?`${r} at period ${e.boundary==="start"?"start":"end"}`:`${r}${e.boundary==="start"?"\u671F\u521D\u503C":"\u671F\u672B\u503C"}`,kind:"component",observationPolicy({pred:r}){const e=r.args?.boundary;if(e!=="start"&&e!=="end")throw new n("INVALID_PERIOD_BOUNDARY_ARGS","$periodBoundary args.boundary must be start or end",{boundary:e});return{boundary:e,implicit:!1}},createComponent({logicform:r,pred:e,outputName:a,schema:i,resolveSchema:y}){if(!e.pred||typeof e.pred!="object"||Array.isArray(e.pred))throw new n("INVALID_PERIOD_BOUNDARY_INPUT","$periodBoundary pred must be a nested metric");const o=e.args?.boundary;if(o!=="start"&&o!=="end")throw new n("INVALID_PERIOD_BOUNDARY_ARGS","$periodBoundary args.boundary must be start or end");const t=c(r.query,e,i,y,"$periodBoundary"),p=o==="start"?t.start:t.end;if(p===void 0)throw new n("PERIOD_BOUNDARY_RANGE_REQUIRED",`$periodBoundary cannot resolve the ${o} of the timestamp query`);const m={version:r.version,schema:i.id,query:{[t.propertyName]:{$lte:p}},preds:[{operator:"$max",pred:t.propertyName,name:"__period_boundary_date__"}]},d=l(r);return d.query=_(t.queryWithoutTime,t.propertyName,m),d.preds=[{...s(e.pred),name:a}],{kind:"query",logicform:d}},getOutputProperty({name:r,inputProperty:e}){if(!e)throw new Error("$periodBoundary requires a nested metric");return{...e,name:r,isArray:!1}}};export{b as periodBoundaryOperator};

package/dist/operators/builtins/period-difference.d.ts

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

package/dist/operators/builtins/period-difference.js

@@ -0,0 +1 @@
+import{clone as n}from"../../utils/clone.js";import{combineQueries as m,collectPredQueries as a,buildPeriodShiftComponent as _}from"./period-shift.js";import{periodComparisonName as d}from"./period-name.js";const y=r=>{const e=n(r);return delete e.having,delete e.sort,delete e.limit,delete e.page,e},$=({logicform:r,pred:e,schema:t,resolveSchema:u})=>{if(!e.pred||typeof e.pred!="object"||Array.isArray(e.pred))throw new Error("$periodDifference pred must be a nested metric");const i=n(e.pred);i.name="__period_difference_current__";const o=y(r);o.preds=[i];const c=m([r.query,...a(e)]);c&&(o.query=c);const f={pred:n(e.pred),...e.args?{args:e.args}:{}},s=_({logicform:r,pred:f,outputName:"__period_difference_previous__",schema:t,resolveSchema:u});if(s.kind!=="query")throw new Error("$periodDifference period shift must produce a query component");return{kind:"cte",components:[{name:"current",component:{kind:"query",logicform:o}},{name:"previous",component:s}],toSQL:({values:p})=>`${p.current} - ${p.previous}`}},h={name:"$periodDifference",defaultName:({operandName:r,args:e,locale:t})=>t.toLowerCase().startsWith("en")?`${r} ${d(e,t)} difference`:`${r}${d(e,t)}\u5DEE\u503C`,kind:"component",createComponent:$,getOutputProperty({name:r,inputProperty:e}){if(!e)throw new Error("$periodDifference requires a nested metric");return{...e,name:r,isArray:!1}}};export{h as periodDifferenceOperator};

package/dist/operators/builtins/period-growth.d.ts

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

package/dist/operators/builtins/period-growth.js

@@ -0,0 +1 @@
+import{clone as n}from"../../utils/clone.js";import{combineQueries as a,collectPredQueries as h,buildPeriodShiftComponent as w}from"./period-shift.js";import{periodComparisonName as d}from"./period-name.js";const y=r=>{const e=n(r);return delete e.having,delete e.sort,delete e.limit,delete e.page,e},_=({logicform:r,pred:e,schema:t,resolveSchema:c})=>{if(!e.pred||typeof e.pred!="object"||Array.isArray(e.pred))throw new Error("$periodGrowth pred must be a nested metric");const i=n(e.pred);i.name="__period_growth_current__";const o=y(r);o.preds=[i];const p=a([r.query,...h(e)]);p&&(o.query=p);const m={pred:n(e.pred),...e.args?{args:e.args}:{}},s=w({logicform:r,pred:m,outputName:"__period_growth_previous__",schema:t,resolveSchema:c});if(s.kind!=="query")throw new Error("$periodGrowth period shift must produce a query component");return{kind:"cte",components:[{name:"current",component:{kind:"query",logicform:o}},{name:"previous",component:s}],toSQL:({values:u})=>`${u.current} / NULLIF(ABS(${u.previous}), 0) - 1`}},f={name:"$periodGrowth",defaultName:({operandName:r,args:e,locale:t})=>t.toLowerCase().startsWith("en")?`${r} ${d(e,t)} growth`:`${r}${d(e,t)}\u589E\u957F\u7387`,kind:"component",createComponent:_,getOutputProperty({name:r}){return{name:r,type:"percentage",primal_type:"number",isArray:!1}}};export{f as periodGrowthOperator};

package/dist/operators/builtins/period-name.d.ts

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

package/dist/operators/builtins/period-name.js

@@ -0,0 +1 @@
+const s=o=>typeof o=="object"&&o!==null&&!Array.isArray(o),f={second:"\u79D2",minute:"\u5206\u949F",hour:"\u5C0F\u65F6",day:"\u65E5",week:"\u5468",month:"\u6708",quarter:"\u5B63\u5EA6",year:"\u5E74"},u={year:"\u5E74",quarter:"\u5B63\u5EA6",month:"\u6708",week:"\u5468",day:"\u65E5",hour:"\u65F6",minute:"\u5206",second:"\u79D2"},y=(o,a)=>{const e=a.toLowerCase().startsWith("en"),r=o.time;if(!s(r))return e?"period-over-period":"\u540C\u671F";if(typeof r.granularity=="string"&&typeof r.offset=="number"){if(r.offset===-1&&r.granularity==="year")return e?"year-over-year":"\u540C\u6BD4";if(r.offset===-1&&r.granularity==="month")return e?"month-over-month":"\u73AF\u6BD4";if(r.offset===-1&&r.granularity==="week")return e?"week-over-week":"\u5468\u73AF\u6BD4";if(r.offset===0)return e?"current-period":"\u672C\u671F";const t=Math.abs(r.offset),n=r.offset<0?"before":"after";return e?`${t} ${r.granularity}${t===1?"":"s"} ${n}`:`\u8F83${n==="before"?"\u524D":"\u540E"}${t}${f[r.granularity]??"\u671F"}`}const i=Object.entries(r).map(([t,n])=>e?`${t} ${String(n)}`:`${String(n)}${u[t]??t}`).join(e?", ":"");return e?`compared with ${i}`:`\u5BF9\u6BD4${i}`};export{y as periodComparisonName};

package/dist/operators/builtins/period-shift.d.ts

@@ -0,0 +1,6 @@
+import type { PredItemType, QueryType } from '../../logicform-types';
+import type { OperatorComponentContext, OperatorDefinition, OperatorExecutionComponent } from '../types';
+export declare const combineQueries: (queries: readonly (QueryType | undefined)[]) => QueryType | undefined;
+export declare const collectPredQueries: (pred: PredItemType) => QueryType[];
+export declare const buildPeriodShiftComponent: ({ logicform, pred, outputName, schema, resolveSchema, }: OperatorComponentContext) => OperatorExecutionComponent;
+export declare const periodShiftOperator: OperatorDefinition;

package/dist/operators/builtins/period-shift.js

@@ -0,0 +1 @@
+import y from"dayjs";import Y from"dayjs/plugin/isoWeek.js";import k from"dayjs/plugin/quarterOfYear.js";import{SemanticDBError as h}from"../../errors.js";import{resolvePropertyPath as A}from"../../schema/resolve-property-path.js";import{clone as I}from"../../utils/clone.js";import{groupbyPropertyReference as E,groupbyOutputName as _}from"../groupby.js";import{periodComparisonName as $}from"./period-name.js";y.extend(Y),y.extend(k);const T=["second","minute","hour","day","week","month","quarter","year"],M=new Set(T),w=["year","quarter","month","week","day","hour","minute","second"],R=r=>Object.prototype.toString.call(r)==="[object Object]",p=r=>{throw new h("INVALID_PERIOD_SHIFT_ARGS",r)},Q=r=>{const t=r.time;R(t)||p("$periodShift requires args.time");const e=t;if("granularity"in e||"offset"in e)return(typeof e.granularity!="string"||!M.has(e.granularity)||!Number.isInteger(e.offset)||Object.keys(e).some(s=>s!=="granularity"&&s!=="offset"))&&p("Relative period shift time requires only granularity and an integer offset"),e;const o=Object.entries(e);(o.length===0||o.some(([s,c])=>!w.includes(s)||!Number.isInteger(c)))&&p("Absolute period shift time requires integer calendar components"),typeof e.year!="number"&&p("Absolute period shift time requires year");const n={quarter:[1,4],month:[1,12],week:[1,53],day:[1,31],hour:[0,23],minute:[0,59],second:[0,59]};for(const[s,[c,u]]of Object.entries(n)){const f=e[s];f!==void 0&&(Number(f)<c||Number(f)>u)&&p(`Invalid absolute period shift ${s}: ${JSON.stringify(f)}`)}return["quarter","month","week"].filter(s=>s in e).length>1&&p("Absolute period shift time cannot mix quarter, month, and week"),"day"in e&&!("month"in e)&&p("Absolute period shift day requires month"),e},j=(r,t,e)=>t==="month"?r.month(e-1):t==="day"?r.date(e):t==="week"?r.isoWeek(e):t==="quarter"?r.quarter(e):r.set(t,e),V=(r,t)=>{if("granularity"in t){const i=t.granularity==="week"?"week":t.granularity;return r.add(t.offset,i)}let e=r;for(const i of w){const o=t[i];typeof o=="number"&&(e=j(e,i,o))}return e},S=(r,t)=>r instanceof Date?t.toDate():typeof r!="string"?r:t.format(r.includes(":")?"YYYY-MM-DD HH:mm:ss":"YYYY-MM-DD"),F=(r,t,e,i,o)=>(r.groupby??[]).filter(n=>{const a=E(n);return a?A(t,a,e).property.primal_type==="date":!1}).map(n=>{const a=n.operator==="$dateBucket"?n.args?.granularity:void 0,s="granularity"in i?i.granularity:a??"day",c="granularity"in i?-i.offset:o.originalAnchor&&o.shiftedAnchor?o.originalAnchor.diff(o.shiftedAnchor,s):0;return{name:_(n),granularity:s,offset:c}}),O=(r,t,e)=>{if(Array.isArray(r))return r.map(n=>O(n,t,e));if(R(r))return Object.fromEntries(Object.entries(r).map(([n,a])=>[n,O(a,t,e)]));if(!(r instanceof Date)&&typeof r!="string")return r;const i=y(r);if(!i.isValid())return r;const o=V(i,t);return e.originalAnchor??=i,e.shiftedAnchor??=o,e.shiftedValues+=1,S(r,o)},G=(r,t,e,i,o)=>{const n=new Set,a=c=>Object.fromEntries(Object.entries(c).map(([u,f])=>{if((u==="$and"||u==="$or")&&Array.isArray(f))return[u,f.map(g=>a(g))];const d=A(t,u,e);return d.property.primal_type!=="date"?[u,f]:(n.add(d.canonicalName),[u,O(f,i,o)])})),s=a(r);if(n.size===0||o.shiftedValues===0)throw new h("PERIOD_SHIFT_TIME_QUERY_REQUIRED","$periodShift requires a concrete date condition in the LogicForm query");if(n.size>1)throw new h("AMBIGUOUS_PERIOD_SHIFT_TIME","$periodShift query contains more than one date property",{properties:[...n]});return s},N=r=>{const t=r.filter(e=>e!==void 0);if(t.length!==0)return t.length===1?t[0]:{$and:t}},l=r=>[...r.query?[r.query]:[],...typeof r.pred=="object"?l(r.pred):[],...(r.components??[]).flatMap(l)],H=(r,t,e)=>{if(!(r instanceof Date)&&typeof r!="string")return r;const i=y(r);if(!i.isValid())return r;if("granularity"in t)return S(r,i.add(-t.offset,t.granularity));if(!e.originalAnchor)return r;let o=i;for(const n of w)if(t[n]!==void 0){const a=n==="month"?e.originalAnchor.month()+1:n==="day"?e.originalAnchor.date():n==="week"?e.originalAnchor.isoWeek():n==="quarter"?e.originalAnchor.quarter():e.originalAnchor.get(n);o=j(o,n,a)}return S(r,o)},P=({logicform:r,pred:t,outputName:e,schema:i,resolveSchema:o})=>{const n=t.pred;(!n||typeof n!="object"||Array.isArray(n))&&p("$periodShift pred must be a nested metric");const a=Q(t.args??{}),s={shiftedValues:0},c=N([r.query,...l(t)]);if(!c)throw new h("PERIOD_SHIFT_TIME_QUERY_REQUIRED","$periodShift requires a date condition in the LogicForm query");const u=G(c,i,o,a,s),f=I(n);f.name=e,delete f.query;const d=I(r);d.query=u,d.preds=[f],delete d.having,delete d.sort,delete d.limit,delete d.page;const g=new Set((r.groupby??[]).filter(b=>{const m=E(b);return m?A(i,m,o).property.primal_type==="date":!1}).map(_));return{kind:"query",logicform:d,groupKeyShifts:F(r,i,o,a,s),mapResult:b=>b.map(m=>{const q={...m};for(const D of g)q[D]=H(q[D],a,s);return q})}},U={name:"$periodShift",defaultName:({operandName:r,args:t,locale:e})=>e.toLowerCase().startsWith("en")?`${r} ${$(t,e)} baseline`:`${r}${$(t,e)}\u57FA\u671F\u503C`,kind:"component",createComponent:P,getOutputProperty({name:r,inputProperty:t}){if(!t)throw new Error("$periodShift requires a nested metric");return{...t,name:r,isArray:!1}}};export{P as buildPeriodShiftComponent,l as collectPredQueries,N as combineQueries,U as periodShiftOperator};

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

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

package/dist/operators/builtins/rank.js

@@ -0,0 +1 @@
+const n={name:"$rank",defaultName:({operandName:t,locale:r})=>r.toLowerCase().startsWith("en")?`${t} rank`:`${t}\u6392\u540D`,kind:"window",windowFunction:"rank",getOutputProperty({name:t}){return{name:t,type:"int",primal_type:"number",isArray:!1}}};export{n as rankOperator};

package/dist/operators/builtins/row-number.d.ts

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

package/dist/operators/builtins/row-number.js

@@ -0,0 +1 @@
+const e={name:"$rowNumber",defaultName:({locale:r})=>r.toLowerCase().startsWith("en")?"Row number":"\u884C\u53F7",kind:"window",windowFunction:"rowNumber",getOutputProperty({name:r}){return{name:r,type:"int",primal_type:"number",isArray:!1}}};export{e as rowNumberOperator};

package/dist/operators/builtins/share-of-total.d.ts

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

package/dist/operators/builtins/share-of-total.js

@@ -0,0 +1 @@
+import{SemanticDBError as a}from"../../errors.js";import{clone as f}from"../../utils/clone.js";import{combineQueries as h,collectPredQueries as T}from"./period-shift.js";import{groupbyOutputName as _}from"../groupby.js";const l=t=>{const e=f(t);return delete e.having,delete e.sort,delete e.limit,delete e.page,e},m=t=>{const e=f(t);return delete e.query,e.pred&&typeof e.pred=="object"&&(e.pred=m(e.pred)),e.components&&(e.components=e.components.map(m)),e},g={name:"$shareOfTotal",defaultName:({operandName:t,locale:e})=>e.toLowerCase().startsWith("en")?`${t} share of total`:`${t}\u5360\u6BD4`,kind:"component",createComponent({logicform:t,pred:e}){if(!e.pred||typeof e.pred!="object")throw new a("INVALID_SHARE_OF_TOTAL_INPUT","$shareOfTotal pred must be a nested metric");const r=e.args?.dimension;if(r!==void 0&&typeof r!="string")throw new a("INVALID_SHARE_OF_TOTAL_ARGS","$shareOfTotal args.dimension must be a groupby pred or output name");const n=t.groupby??[],p=r===void 0?n.length-1:n.findIndex(o=>typeof o.pred=="string"&&o.pred===r||_(o)===r);if(r!==void 0&&p<0)throw new a("SHARE_OF_TOTAL_DIMENSION_NOT_FOUND",`$shareOfTotal dimension is not grouped: ${r}`);const d=n.filter((o,O)=>O!==p),y=d.map(_),u=m(e.pred),s=l(t);s.preds=[{...u,name:"__share_numerator__"}];const c=h([t.query,...T(e)]);c&&(s.query=c);const i=l(t);return i.groupby=d,i.preds=[{...u,name:"__share_denominator__"}],{kind:"cte",components:[{name:"numerator",component:{kind:"query",logicform:s}},{name:"denominator",component:{kind:"query",logicform:i},joinKeys:y}],toSQL:({values:o})=>`${o.numerator} / NULLIF(${o.denominator}, 0)`}},getOutputProperty({name:t}){return{name:t,type:"percentage",primal_type:"number",isArray:!1}}};export{g as shareOfTotalOperator};

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

@@ -0,0 +1,3 @@
+import type { OperatorDefinition } from '../types';
+/** Trusted raw SQL expression with separately bound dynamic parameters. */
+export declare const sqlOperator: OperatorDefinition;

package/dist/operators/builtins/sql.js

@@ -0,0 +1 @@
+import{SemanticDBError as s}from"../../errors.js";import{bindTrustedSqlExpression as a}from"../sql-expression.js";const i=new Set(["boolean","date","number","object","string"]),p=r=>{if(r===void 0)return[];if(!Array.isArray(r))throw new s("INVALID_SQL_ARGS","$sql args.parameters must be an array");return r},l=(r,e)=>{const t=e.type,n=e.primal_type;if(typeof t!="string"||t.length===0||!i.has(n))throw new s("INVALID_SQL_OUTPUT","$sql requires args.type and a valid args.primal_type");if(e.isArray!==void 0&&typeof e.isArray!="boolean")throw new s("INVALID_SQL_OUTPUT","$sql args.isArray must be boolean");if(e.ref!==void 0&&typeof e.ref!="string")throw new s("INVALID_SQL_OUTPUT","$sql args.ref must be a Schema id");return{name:r,type:t,primal_type:n,isArray:e.isArray===!0,...typeof e.ref=="string"?{ref:e.ref}:{}}},f={name:"$sql",defaultName:({locale:r})=>r.toLowerCase().startsWith("en")?"Calculated value":"\u8BA1\u7B97\u503C",kind:"scalar",requiresProperty:!1,toSQL({args:r,expression:e,expressions:t,sql:n}){if(e||t&&t.length>0)throw new s("INVALID_SQL_INPUT","$sql does not accept pred or components; put the expression in args.sql");return a(r.sql,p(r.parameters),o=>n.value(o))},getOutputProperty({name:r,args:e,inputProperty:t,componentProperties:n}){if(t||n&&n.length>0)throw new s("INVALID_SQL_INPUT","$sql does not accept pred or components; put the expression in args.sql");return l(r,e)}};export{f as sqlOperator};

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

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

package/dist/operators/builtins/substring.js

@@ -0,0 +1 @@
+import{SemanticDBError as n}from"../../errors.js";const u={name:"$substring",defaultName:({operandName:r,locale:t})=>t.toLowerCase().startsWith("en")?`${r} substring`:`${r}\u5B50\u4E32`,kind:"scalar",toSQL({expression:r,args:t,sql:i}){if(!r)throw new n("PRED_PROPERTY_REQUIRED","$substring requires a pred");const{start:e,length:s}=t;if(!Number.isInteger(e)||Number(e)<0||!Number.isInteger(s)||Number(s)<1)throw new n("INVALID_SUBSTRING_ARGS","$substring requires a non-negative integer start and a positive integer length");return i.substring(r,Number(e)+1,Number(s))},getOutputProperty({name:r}){return{name:r,type:"string",primal_type:"string",isArray:!1}}};export{u as substringOperator};

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

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

package/dist/operators/builtins/subtract.js

@@ -0,0 +1 @@
+import{numericResult as s,requireExpressions as u}from"./arithmetic.js";const i={name:"$subtract",defaultName:({operandName:t,componentNames:r,locale:e})=>e.toLowerCase().startsWith("en")?r.length>=2?`${r[0]} minus ${r[1]}`:`${t} difference`:r.length>=2?`${r[0]}\u51CF\u53BB${r[1]}`:`${t}\u5DEE\u503C`,kind:"scalar",requiresProperty:!1,toSQL(t){const[r,e]=u("$subtract",t,2);return`(${r} - ${e})`},getOutputProperty({name:t,componentProperties:r}){const e=r?.[0];return e?{...e,name:t,isArray:!1}:s(t)}};export{i as subtractOperator};

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

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

package/dist/operators/builtins/sum.js

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

package/dist/operators/builtins/time-range.d.ts

@@ -0,0 +1,13 @@
+import type { PredItemType, QueryType } from '../../logicform-types';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../semantic-types/index';
+export interface ResolvedTimeRange {
+    readonly property: ResolvedSemanticProperty;
+    readonly propertyName: string;
+    readonly start?: string | number | Date;
+    readonly end?: string | number | Date;
+    readonly queryWithoutTime?: QueryType;
+}
+export declare const requireTimestampProperty: (schema: ResolvedSemanticSchema, operator: string) => ResolvedSemanticProperty;
+export declare const resolveTimeRange: (query: QueryType, schema: ResolvedSemanticSchema, resolveSchema: (schemaId: string) => ResolvedSemanticSchema, operator: string) => ResolvedTimeRange;
+export declare const resolvePredTimeRange: (logicformQuery: QueryType | undefined, pred: PredItemType, schema: ResolvedSemanticSchema, resolveSchema: (schemaId: string) => ResolvedSemanticSchema, operator: string) => ResolvedTimeRange;
+export declare const withTimeCondition: (query: QueryType | undefined, propertyName: string, condition: unknown) => QueryType;

package/dist/operators/builtins/time-range.js

@@ -0,0 +1 @@
+import{SemanticDBError as y}from"../../errors.js";import{resolvePropertyPath as R}from"../../schema/resolve-property-path.js";import{combineQueries as U,collectPredQueries as I}from"./period-shift.js";const _=t=>typeof t=="object"&&t!==null&&!Array.isArray(t)&&!(t instanceof Date),h=t=>typeof t=="string"||typeof t=="number"||t instanceof Date,T=(t,e)=>{const r=t.properties.find(({type:s})=>s==="timestamp");if(!r)throw new y("TIMESTAMP_PROPERTY_REQUIRED",`${e} requires a timestamp property in the Schema`);return r},w=(t,e)=>{if(h(t)){e.start??=t,e.end??=t;return}if(!_(t))return;const r=t.$eq;h(r)&&(e.start??=r,e.end??=r);const s=t.$gte??t.$gt,i=t.$lte??t.$lt;h(s)&&(e.start??=s),h(i)&&(e.end??=i);for(const o of["$and","$or"]){const a=t[o];if(Array.isArray(a))for(const u of a)w(u,e)}},A=(t,e,r,s)=>{const i=T(e,s),o=new Set,a={},u=(E,c)=>{for(const[n,f]of Object.entries(E)){if((n==="$and"||n==="$or")&&Array.isArray(f)){for(const m of f)u(m,c||n==="$or");continue}if(n.startsWith("$"))continue;const p=R(e,n,r);if(p.property.type==="timestamp"){if(c)throw new y("AMBIGUOUS_TIME_QUERY",`${s} does not support timestamp conditions inside $or`);o.add(p.canonicalName),w(f,a)}}};if(u(t,!1),o.size!==1)throw new y(o.size===0?"TIME_QUERY_REQUIRED":"AMBIGUOUS_TIME_QUERY",`${s} requires a concrete condition on the Schema timestamp property`);const $=[...o][0];if(!$||$!==i.name)throw new y("AMBIGUOUS_TIME_QUERY",`${s} requires the Schema timestamp property: ${i.name}`);const l=E=>{const c=[];for(const[n,f]of Object.entries(E)){if((n==="$and"||n==="$or")&&Array.isArray(f)){const p=f.map(m=>l(m)).filter(m=>m!==void 0);p.length>0&&c.push([n,p]);continue}!n.startsWith("$")&&R(e,n,r).property.type==="timestamp"||c.push([n,f])}return c.length>0?Object.fromEntries(c):void 0},d=l(t);return{property:i,propertyName:$,...a.start!==void 0?{start:a.start}:{},...a.end!==void 0?{end:a.end}:{},...d?{queryWithoutTime:d}:{}}},M=(t,e,r,s,i)=>{const o=U([t,...I(e)]);if(!o)throw new y("TIME_QUERY_REQUIRED",`${i} requires a timestamp query`);return A(o,r,s,i)},Q=(t,e,r)=>U([t,{[e]:r}]);export{T as requireTimestampProperty,M as resolvePredTimeRange,A as resolveTimeRange,Q as withTimeCondition};

package/dist/operators/groupby.d.ts

@@ -0,0 +1,3 @@
+import type { PredItemType } from '../logicform-types';
+export declare const groupbyOutputName: (group: PredItemType) => string;
+export declare const groupbyPropertyReference: (group: PredItemType) => string | undefined;

package/dist/operators/groupby.js

@@ -0,0 +1 @@
+import{SemanticDBError as r}from"../errors.js";const t=e=>{if(e.name)return e.name;throw new r("MISSING_PRED_NAME","A normalized groupby PredItem must have a name")},n=e=>typeof e.pred=="string"?e.pred:void 0;export{t as groupbyOutputName,n as groupbyPropertyReference};

package/dist/operators/index.d.ts

@@ -0,0 +1,7 @@
+import type { SemanticDBPlugin } from '../plugins/index';
+import { OperatorRegistry } from './registry';
+export { OperatorRegistry } from './registry';
+export { bindTrustedSqlExpression } from './sql-expression';
+export type { OperatorDefinition, OperatorDefaultNameContext, OperatorComponentContext, OperatorCteCalculation, OperatorCteComponent, OperatorCteSqlContext, OperatorExecutionComponent, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorObservationPolicy, OperatorObservationPolicyContext, OperatorNormalizePredContext, OperatorPlanExpressionContext, OperatorPeriodEvaluationContext, OperatorPlanInputContext, OperatorPlannedInput, OperatorRewriteLogicformContext, OperatorValidatePlanContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, } from './types';
+export declare const builtinOperators: readonly import("./types").OperatorDefinition[];
+export declare const createOperatorRegistry: (plugins?: readonly SemanticDBPlugin[]) => OperatorRegistry;

package/dist/operators/index.js

@@ -0,0 +1 @@
+import{builtinOperators as t}from"./builtins/index.js";import{builtinPlugins as o,resolvePlugins as a}from"../plugins/index.js";import{OperatorRegistry as e}from"./registry.js";const p=Object.freeze([...t,...o.flatMap(({operators:r})=>r??[])]),s=(r=[])=>new e([...t,...a(r).flatMap(({operators:i})=>i??[])]);export{e as OperatorRegistry,p as builtinOperators,s as createOperatorRegistry};

package/dist/operators/registry.d.ts

@@ -0,0 +1,10 @@
+import type { OperatorDefinition, OperatorPeriodEvaluationContext } from './types';
+export declare class OperatorRegistry {
+    #private;
+    constructor(definitions?: readonly OperatorDefinition[]);
+    register(definition: OperatorDefinition): this;
+    get(name: string): OperatorDefinition;
+    requiresPerPeriodEvaluation(name: string, context: OperatorPeriodEvaluationContext): boolean;
+    has(name: string): boolean;
+    definitions(): readonly OperatorDefinition[];
+}

package/dist/operators/registry.js

@@ -0,0 +1 @@
+import{SemanticDBError as r}from"../errors.js";class n{#e=new Map;constructor(e=[]){for(const t of e)this.register(t)}register(e){if(!e.name)throw new r("INVALID_OPERATOR","Operator name must not be empty");if(typeof e.defaultName!="function")throw new r("INVALID_OPERATOR",`Operator must implement defaultName: ${e.name}`);if(this.#e.has(e.name))throw new r("OPERATOR_ALREADY_REGISTERED",`Operator is already registered: ${e.name}`,{operator:e.name});const t=e;if(!(t.kind==="scalar"&&(typeof t.toSQL=="function"||typeof t.evaluate=="function")||t.kind==="aggregate"&&typeof t.toSQL=="function"||t.kind==="component"&&typeof t.createComponent=="function"||t.kind==="window"&&typeof t.windowFunction=="string"||t.kind==="logical"&&typeof t.planExpression=="function"))throw new r("INVALID_OPERATOR",`Operator kind and implementation do not match: ${e.name}`);return this.#e.set(e.name,e),this}get(e){const t=this.#e.get(e);if(!t)throw new r("OPERATOR_NOT_FOUND",`Operator is not registered: ${e}`,{operator:e});return t}requiresPerPeriodEvaluation(e,t){return this.get(e).requiresPerPeriodEvaluation?.(t)??!1}has(e){return this.#e.has(e)}definitions(){return[...this.#e.values()]}}export{n as OperatorRegistry};

package/dist/operators/sql-expression.d.ts

@@ -0,0 +1 @@
+export declare const bindTrustedSqlExpression: (expression: unknown, parameters: readonly unknown[], bind: (value: unknown) => string, subject?: string) => string;

package/dist/operators/sql-expression.js

@@ -0,0 +1 @@
+import{SemanticDBError as a}from"../errors.js";const f=(o,s,c,i="$sql")=>{if(typeof o!="string"||o.trim().length===0)throw new a("INVALID_SQL_ARGS",`${i} requires a non-empty args.sql expression`);let r="",l=0,n;for(let t=0;t<o.length;t+=1){const e=o[t];if(!e)continue;if(n){r+=e,e===n&&(o[t+1]===n?(r+=n,t+=1):n=void 0);continue}if(e==="'"||e==='"'||e==="`"){n=e,r+=e;continue}const S=o.slice(t,t+2);if(e===";"||S==="--"||S==="/*")throw new a("INVALID_SQL_EXPRESSION",`${i} accepts one expression and does not allow statements or SQL comments`);if(e==="?"){if(l>=s.length)throw new a("INVALID_SQL_PARAMETERS",`${i} contains more placeholders than args.parameters values`);r+=c(s[l]),l+=1;continue}r+=e}if(n)throw new a("INVALID_SQL_EXPRESSION",`${i} contains an unterminated quote`);if(l!==s.length)throw new a("INVALID_SQL_PARAMETERS",`${i} args.parameters contains more values than SQL placeholders`);return r};export{f as bindTrustedSqlExpression};

package/dist/operators/types.d.ts

@@ -0,0 +1,277 @@
+import type { PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, TimeGranularity, ComparableCategoryDefinition } from '../semantic-types/index';
+import type { LogicformType, PredItemType } from '../logicform-types';
+import type { DataRow } from '../physical/index';
+import type { Expression } from '../planner/index';
+export interface OperatorSqlCapabilities {
+    /** Produce a dialect-specific aggregate function around an expression. */
+    aggregateFunction(name: string, expression?: string): string;
+    /** Quote an identifier or an alias according to the active dialect. */
+    quoteIdentifier(identifier: string): string;
+    concat(expressions: readonly string[]): string;
+    substring(expression: string, start: number, length: number): string;
+    dateBucket(expression: string, granularity: TimeGranularity): string;
+    /** Bind a literal as a SQL parameter. */
+    value(value: unknown): string;
+    /** Compile a field-local LogicForm condition against an expression. */
+    condition(expression: string, condition: unknown): string;
+}
+/** Context passed to an operator that pushes its computation into SQL. */
+export interface OperatorSqlContext {
+    readonly sql: OperatorSqlCapabilities;
+    /** SQL for the nested input expression, when this operator has one. */
+    readonly expression?: string;
+    /** SQL expressions produced by a multi-input operator's structural components. */
+    readonly expressions?: readonly string[];
+    /** Quoted physical column for a leaf-property operator. */
+    readonly column?: string;
+    /** Operator-specific LogicForm arguments. */
+    readonly args: Readonly<Record<string, unknown>>;
+}
+/** Context passed to an operator evaluated after the provider returns rows. */
+export interface OperatorEvaluateContext {
+    /** Value produced by the nested expression, or undefined for a propertyless operator. */
+    readonly input: unknown;
+    /** Operator-specific LogicForm arguments. */
+    readonly args: Readonly<Record<string, unknown>>;
+}
+/** A logical output column produced by one LogicForm projection. */
+export interface ResultProperty {
+    readonly name: string;
+    readonly type: string;
+    readonly primal_type: PrimalType;
+    readonly isArray: boolean;
+    /** Referenced Schema for object-valued result columns. */
+    readonly ref?: string;
+    readonly granularity?: TimeGranularity;
+    readonly comparable?: ComparableCategoryDefinition;
+    /** Runtime temporal semantics for this output column, when applicable. */
+    readonly temporal?: ResultPropertyTemporalMetadata;
+}
+export interface ResultPropertyTemporalMetadata {
+    readonly kind: 'period-boundary' | 'period-shift' | 'date-bucket' | 'lifecycle';
+    readonly boundary?: 'start' | 'end';
+    readonly sourceProperty?: string;
+    readonly requestedRange?: {
+        readonly gte?: string;
+        readonly lte?: string;
+    };
+    readonly effectiveRange?: {
+        readonly gte?: string;
+        readonly lte?: string;
+    };
+    readonly resolvedAt?: string;
+    readonly shiftedBy?: {
+        readonly granularity: TimeGranularity;
+        readonly offset: number;
+    };
+    readonly resolvedAtByGroup?: readonly {
+        readonly group: Readonly<Record<string, unknown>>;
+        readonly date: string;
+    }[];
+}
+export interface OperatorOutputPropertyContext {
+    /** Final alias assigned to this operator's single output column. */
+    readonly name: string;
+    /** Original Schema property when the operator starts from a physical property. */
+    readonly property?: ResolvedSemanticProperty;
+    /** Semantic metadata produced by a nested expression. */
+    readonly inputProperty?: ResultProperty;
+    /** Semantic metadata produced by structural components. */
+    readonly componentProperties?: readonly ResultProperty[];
+    /** Operator-specific LogicForm arguments. */
+    readonly args: Readonly<Record<string, unknown>>;
+}
+/** Context used by operators whose value must be evaluated per time bucket. */
+export interface OperatorPeriodEvaluationContext {
+    readonly logicform: LogicformType;
+    readonly pred: PredItemType;
+    readonly schema: ResolvedSemanticSchema;
+    readonly inputProperty?: ResolvedSemanticProperty;
+}
+export interface OperatorDefaultNameContext {
+    /** Name produced by the direct pred, structural components, or localized row label. */
+    readonly operandName: string;
+    /** Name of a direct or nested pred input. */
+    readonly inputName?: string;
+    /** Names of structural component inputs. */
+    readonly componentNames: readonly string[];
+    /** Operator-specific LogicForm arguments. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Requested locale. Each operator owns its own localized default names. */
+    readonly locale: string;
+}
+export interface OperatorPlanInputContext {
+    /** Canonical property or relation reference supplied as this operator's direct pred. */
+    readonly reference: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly schema: ResolvedSemanticSchema;
+    readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
+}
+export interface OperatorPlannedInput {
+    /** Property reference the generic expression planner should consume. */
+    readonly reference: string;
+    /** Provider-independent arguments resolved from semantic metadata. */
+    readonly args: Readonly<Record<string, unknown>>;
+}
+export interface OperatorNormalizePredContext {
+    readonly pred: PredItemType;
+    readonly schema: ResolvedSemanticSchema;
+}
+export interface OperatorPlanExpressionContext {
+    readonly pred: PredItemType;
+    readonly input?: Expression;
+    readonly inputProperty?: ResultProperty;
+    readonly components: readonly Expression[];
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly resolveKey: (reference: string) => Expression;
+    readonly getOperator: (name: string) => OperatorDefinition;
+    readonly planQuery: (query: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>>;
+}
+export interface OperatorObservationPolicyContext {
+    readonly pred: PredItemType;
+}
+export interface OperatorObservationPolicy {
+    readonly boundary: 'start' | 'end';
+    readonly implicit: boolean;
+}
+export interface OperatorValidatePlanContext {
+    readonly pred: PredItemType;
+    readonly groupByNames: readonly string[];
+    readonly resolveGroupName: (reference: string) => string | undefined;
+    readonly getOperator: (name: string) => OperatorDefinition;
+}
+export interface OperatorRewriteLogicformContext {
+    readonly logicform: LogicformType;
+    readonly schema: ResolvedSemanticSchema;
+}
+export interface OperatorComponentContext {
+    /** Fully normalized LogicForm containing this top-level operator projection. */
+    readonly logicform: LogicformType;
+    /** Caller-authored normalized LogicForm before executor row policies were added. */
+    readonly sourceLogicform?: LogicformType;
+    /** The operator projection for which the component is being built. */
+    readonly pred: PredItemType;
+    /** Final output alias assigned by the planner. */
+    readonly outputName: string;
+    readonly schema: ResolvedSemanticSchema;
+    /** Resolve Schemas referenced by object relation paths used by this component. */
+    readonly resolveSchema: (schemaId: string) => ResolvedSemanticSchema;
+}
+export interface OperatorGroupKeyShift {
+    readonly name: string;
+    readonly granularity: TimeGranularity;
+    readonly offset: number;
+}
+export interface OperatorQueryComponent {
+    readonly kind: 'query';
+    /** Internal LogicForm executed by the normal planner/compiler/provider pipeline. */
+    readonly logicform: LogicformType;
+    /** Apply permissions and normalize this dynamically generated LogicForm before planning. */
+    readonly prepare?: boolean;
+    /** Optional result-key mapping used before component rows are merged. */
+    readonly mapResult?: (rows: readonly DataRow[]) => DataRow[];
+    /** SQL-side transformations that align this component's group keys with the base component. */
+    readonly groupKeyShifts?: readonly OperatorGroupKeyShift[];
+}
+export interface OperatorCteSqlContext {
+    readonly values: Readonly<Record<string, string>>;
+    readonly quoteIdentifier: (identifier: string) => string;
+}
+export interface OperatorCteComponent {
+    readonly name: string;
+    readonly component: OperatorQueryComponent;
+    /** Group output names used to join this component back to the first component. */
+    readonly joinKeys?: readonly string[];
+}
+export interface OperatorCteCalculation {
+    readonly kind: 'cte';
+    readonly components: readonly OperatorCteComponent[];
+    readonly outputName?: string;
+    readonly toSQL: (context: OperatorCteSqlContext) => string;
+    readonly exposeComponents?: boolean;
+}
+export interface OperatorJavaScriptCalculation {
+    readonly kind: 'js';
+    readonly components: readonly OperatorCteComponent[];
+    readonly outputName: string;
+    readonly mergeRow: (values: DataRow) => unknown;
+    readonly exposeComponents?: boolean;
+}
+export type OperatorExecutionComponent = OperatorQueryComponent | OperatorCteCalculation | OperatorJavaScriptCalculation;
+/**
+ * Extension contract for one LogicForm operator.
+ *
+ * `kind` is the semantic category used by planning and execution. Its variant
+ * requires the corresponding SQL, JavaScript, window, or component contract.
+ * The planner recursively connects nested `pred` expressions and uses
+ * `getOutputProperty` to describe the resulting one-column logical schema.
+ */
+interface OperatorDefinitionBase {
+    /** Public registry key, normally using the `$name` convention. */
+    readonly name: string;
+    /** Produce the normalized output name when the PredItem does not declare one. */
+    readonly defaultName: (context: OperatorDefaultNameContext) => string;
+    /** Logical property names read in addition to the direct input property. */
+    readonly dependencies?: readonly string[];
+    /** Set to false for operators such as `$count` that do not require a property. */
+    readonly requiresProperty?: boolean;
+    /** Output metadata hook. It must describe exactly one result column. */
+    readonly getOutputProperty?: (context: OperatorOutputPropertyContext) => ResultProperty;
+    /** Resolve Schema-dependent input and arguments before creating a logical expression. */
+    readonly planInput?: (context: OperatorPlanInputContext) => OperatorPlannedInput;
+    /** Validate or canonicalize this operator after its nested inputs are normalized. */
+    readonly normalizePred?: (context: OperatorNormalizePredContext) => PredItemType;
+    /** Build a provider-independent expression for operators with custom planning semantics. */
+    readonly planExpression?: (context: OperatorPlanExpressionContext) => Expression | undefined;
+    /** Resolve observation temporal semantics for this operator, when applicable. */
+    readonly observationPolicy?: (context: OperatorObservationPolicyContext) => OperatorObservationPolicy | undefined;
+    /** Validate this operator against the completed group key set. */
+    readonly validatePlan?: (context: OperatorValidatePlanContext) => void;
+    /** Expand high-level operator semantics into ordinary nested LogicForms before planning. */
+    readonly rewriteLogicform?: (context: OperatorRewriteLogicformContext) => LogicformType | undefined;
+    /** Whether this operator requires one evaluation per time bucket. */
+    readonly requiresPerPeriodEvaluation?: (context: OperatorPeriodEvaluationContext) => boolean;
+}
+export type OperatorWindowFunction = 'rank' | 'rowNumber';
+export type OperatorDefinition = OperatorDefinitionBase & ({
+    readonly kind: 'scalar';
+    /** Convert the operator and its input expression into SQL. */
+    readonly toSQL: (context: OperatorSqlContext) => string;
+    readonly evaluate?: (context: OperatorEvaluateContext) => unknown;
+    readonly createComponent?: never;
+    readonly windowFunction?: never;
+} | {
+    readonly kind: 'scalar';
+    readonly toSQL?: (context: OperatorSqlContext) => string;
+    /** JavaScript evaluator for this operator. */
+    readonly evaluate: (context: OperatorEvaluateContext) => unknown;
+    readonly createComponent?: never;
+    readonly windowFunction?: never;
+} | {
+    readonly kind: 'aggregate';
+    readonly toSQL: (context: OperatorSqlContext) => string;
+    readonly evaluate?: (context: OperatorEvaluateContext) => unknown;
+    readonly createComponent?: never;
+    readonly windowFunction?: never;
+} | {
+    readonly kind: 'component';
+    readonly toSQL?: never;
+    readonly evaluate?: never;
+    readonly createComponent: (context: OperatorComponentContext) => OperatorExecutionComponent;
+    readonly windowFunction?: never;
+} | {
+    readonly kind: 'window';
+    readonly toSQL?: never;
+    readonly evaluate?: never;
+    readonly createComponent?: never;
+    /** Plan this operator as a SQL window expression. */
+    readonly windowFunction: OperatorWindowFunction;
+} | {
+    readonly kind: 'logical';
+    readonly toSQL?: never;
+    readonly evaluate?: never;
+    readonly createComponent?: never;
+    readonly windowFunction?: never;
+    readonly planExpression: (context: OperatorPlanExpressionContext) => Expression;
+});
+export {};

package/dist/permissions/index.d.ts

@@ -0,0 +1,3 @@
+export { applyPermissions, assertLogicformAllowed, getSchemaPermissions, isColumnAllowed, validatePermissions, } from './permissions';
+export type { PermissionSchemaResolver, } from './permissions';
+export type { ColumnPermissions, Permissions, SchemaPermissions, } from './types';

package/dist/permissions/permissions.d.ts

@@ -0,0 +1,10 @@
+import type { LogicformType } from '../logicform-types';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../semantic-types/index';
+import type { Permissions, SchemaPermissions } from './types';
+import type { SemanticDBPlugin } from '../plugins/index';
+export type PermissionSchemaResolver = (schemaId: string) => ResolvedSemanticSchema;
+export declare const getSchemaPermissions: (permissions: Permissions | undefined, schemaId: string) => SchemaPermissions | undefined;
+export declare const isColumnAllowed: (permissions: Permissions | undefined, schemaId: string, property: Pick<ResolvedSemanticProperty, "id" | "name">) => boolean;
+export declare const assertLogicformAllowed: (logicform: LogicformType, permissions: Permissions | undefined, resolveSchema: PermissionSchemaResolver, plugins?: readonly SemanticDBPlugin[]) => void;
+export declare const applyPermissions: (logicform: LogicformType, permissions: Permissions | undefined, resolveSchema: PermissionSchemaResolver, authorize?: boolean, appliedSchemas?: ReadonlySet<string>, plugins?: readonly SemanticDBPlugin[]) => LogicformType;
+export declare const validatePermissions: (permissions: Permissions | undefined, resolveSchema: PermissionSchemaResolver) => void;

package/dist/permissions/permissions.js

@@ -0,0 +1 @@
+import{SemanticDBError as A}from"../errors.js";import{isLogicform as D}from"../logicform-types.js";import{resolvePropertyPath as _}from"../schema/resolve-property-path.js";import{isConcreteEntityId as L,resolveEntityFilterProperty as C}from"../schema/entity-identity.js";import{clone as E}from"../utils/clone.js";const q=(t,e)=>Object.prototype.hasOwnProperty.call(t,e),u=(t,e)=>{if(t){if(!q(t,e))throw new A("TABLE_PERMISSION_DENIED",`Schema is not included in the table permissions: ${e}`,{schemaId:e});return t[e]}},M=(t,e,r)=>{const n=u(t,e)?.columnPermissions?.whitelist;return!n||n.includes(r.name)||n.includes(r.id)},p=(t,e,r)=>{if(!M(t,e.id,r))throw new A("COLUMN_PERMISSION_DENIED",`Property is not included in the column permissions: ${e.id}.${r.name}`,{schemaId:e.id,property:r.name,propertyId:r.id})},Q=(t,e,r,n)=>{const f=_(e,t,n);for(const o of f.relations)u(r,o.targetSchema.id),p(r,o.sourceSchema,o.property);p(r,f.schema,f.property)},U=t=>typeof t=="object"&&t!==null&&!Array.isArray(t)&&typeof t.schema=="string"&&typeof t.query=="object"&&t.query!==null&&!Array.isArray(t.query),F=(t,e,r,n)=>{if(typeof t!="object"||t===null||Array.isArray(t)||!q(t,"$recursive"))return;const f=t.$recursive,o=typeof f=="object"&&f!==null&&!Array.isArray(f)?f:{},s=typeof o.schema=="string"?o.schema:e.property.ref??e.schema.id,c=n(s);if(u(r,s)?.rowPermissions!==void 0)throw new A("RECURSIVE_ROW_PERMISSION_UNSUPPORTED",`$recursive cannot safely apply row permissions for Schema ${s}`,{schemaId:s});const i=o.idProperty??o.id_property,w=i===void 0?c.properties.find(({type:d})=>d==="ID"):c.properties.find(({id:d,name:b})=>d===i||b===i),a=o.parentProperty??o.parent_property??c.parentProperty??"pid",P=c.properties.find(({id:d,name:b})=>d===a||b===a);w&&p(r,c,w),P&&p(r,c,P)},N=(t,e,r,n)=>{if(D(t)){O(t,e,r,n);return}if(Array.isArray(t)){for(const f of t)N(f,e,r,n);return}if(!(typeof t!="object"||t===null||t instanceof Date))for(const f of Object.values(t))N(f,e,r,n)},m=(t,e,r,n,f)=>{if(t)for(const[o,s]of Object.entries(t)){if(o==="$and"||o==="$or"){if(Array.isArray(s))for(const y of s)m(y,e,r,n,f);continue}const c=_(e,o,n);if(Q(o,e,r,n),F(s,c,r,n),U(s)){if(c.property.ref!==s.schema)continue;const y=n(s.schema);u(r,y.id),L(s.entity_id)&&p(r,y,C(y,f)),m(s.query,y,r,n,f);continue}N(s,r,n,f)}},j=(t,e,r,n,f)=>{const o=t.schema?n(t.schema):e;t.schema&&u(r,t.schema),typeof t.pred=="string"?Q(t.pred,o,r,n):t.pred&&j(t.pred,o,r,n,f);for(const s of t.components??[])j(s,o,r,n,f);m(t.query,o,r,n,f)},O=(t,e,r,n=[])=>{if(t.logicforms){for(const o of t.logicforms)O(o,e,r,n);return}if(!t.schema){if(t.from){O(t.from,e,r,n);return}throw new A("LOGICFORM_SCHEMA_REQUIRED","A physical LogicForm must define schema")}const f=r(t.schema);if(u(e,f.id),L(t.entity_id)&&p(e,f,C(f,n)),t.from){O(t.from,e,r,n);return}m(t.query,f,e,r,n);for(const o of t.preds??[])j(o,f,e,r,n);for(const o of t.groupby??[])j(o,f,e,r,n)},R=(t,e)=>{if(Array.isArray(t))return t.map(f=>R(f,e));if(typeof t!="object"||t===null||t instanceof Date)return t;const r=Object.entries(t).map(([f,o])=>[f,R(o,e)]),n=Object.fromEntries(r);return U(t)&&!q(t,"version")&&(n.version=e),n},T=(t,e,r)=>{const n=[],f=c=>{n.push(_(e,c,r))},o=c=>{if(c)for(const[y,i]of Object.entries(c))if((y==="$and"||y==="$or")&&Array.isArray(i))for(const w of i)o(w);else y.startsWith("$")||f(y)},s=c=>{typeof c.pred=="string"?f(c.pred):c.pred&&s(c.pred);for(const y of c.components??[])s(y);o(c.query)};o(t.query);for(const c of t.preds??[])s(c);for(const c of t.groupby??[])s(c);return n},V=(t,e,r)=>{if(!t.schema)return[];const n=r(t.schema),f=new Set,o=[];for(const s of T(t,n,r)){if(s.relations.length===0)continue;let c=-1;if(s.relations.forEach(({targetSchema:a},P)=>{e[a.id]?.rowPermissions!==void 0&&(c=P)}),c<0)continue;const y=s.relations.slice(0,c+1),i=y.map(({property:a})=>a.name).join("_");if(f.has(i))continue;f.add(i);let w={};for(const a of[...y].reverse())w={[a.property.name]:{schema:a.targetSchema.id,query:w}};o.push(w)}return o},I=(t,e,r,n,f,o)=>D(t)?h(t,e,r,n,f,o):Array.isArray(t)?t.map(s=>I(s,e,r,n,f,o)):typeof t!="object"||t===null||t instanceof Date?t:Object.fromEntries(Object.entries(t).map(([s,c])=>[s,I(c,e,r,n,f,o)])),$=(t,e,r,n,f,o)=>({...t,...t.query?{query:I(t.query,e,r,n,f,o)}:{},...t.pred&&typeof t.pred=="object"?{pred:$(t.pred,e,r,n,f,o)}:{},...t.components?{components:t.components.map(s=>$(s,e,r,n,f,o))}:{}}),h=(t,e,r,n=!0,f=new Set,o=[])=>{if(!e)return E(t);if(t.logicforms){const d=E(t);return d.logicforms=t.logicforms.map(b=>h(b,e,r,n,new Set,o)),d}if(!t.schema){const d=E(t);return d.from&&(d.from=h(d.from,e,r,n,new Set,o)),d}n&&O(t,e,r,o);const s=u(e,t.schema),c=f.has(t.schema),y=new Set(f).add(t.schema),i=E(t);i.query&&(i.query=I(i.query,e,r,n,new Set,o)),i.preds&&(i.preds=i.preds.map(d=>$(d,e,r,n,new Set,o))),i.from&&(i.from=h(i.from,e,r,n,new Set,o));const w=c||t.from?void 0:s?.rowPermissions,a=(t.from?[]:V(t,e,r)).map(d=>I(R(d,t.version),e,r,!1,y,o));w&&a.push(I(R(E(w),t.version),e,r,!1,y,o));const P=[i.query,...a].filter(d=>d!==void 0&&Object.keys(d).length>0);return P.length===1?i.query=P[0]:P.length>1?i.query={$and:P}:delete i.query,i},k=(t,e)=>{if(t)for(const[r,n]of Object.entries(t)){const f=e(r),o=n.columnPermissions?.whitelist;if(o&&(!Array.isArray(o)||o.some(s=>typeof s!="string")))throw new A("INVALID_COLUMN_PERMISSIONS",`Column permissions whitelist must be an array of strings: ${r}`,{schemaId:r});for(const s of o??[])if(!f.properties.some(({id:c,name:y})=>c===s||y===s))throw new A("INVALID_COLUMN_PERMISSION",`Column permission property not found: ${r}.${s}`,{schemaId:r,property:s})}};export{h as applyPermissions,O as assertLogicformAllowed,u as getSchemaPermissions,M as isColumnAllowed,k as validatePermissions};

package/dist/permissions/types.d.ts

@@ -0,0 +1,12 @@
+import type { QueryType } from '../logicform-types';
+export interface ColumnPermissions {
+    readonly whitelist: readonly string[];
+}
+export interface SchemaPermissions {
+    readonly rowPermissions?: QueryType;
+    readonly columnPermissions?: ColumnPermissions;
+}
+/**
+ * Schema-keyed execution permissions. When present, the keys are the table allowlist.
+ */
+export type Permissions = Readonly<Record<string, SchemaPermissions>>;

package/dist/physical/clickhouse-provider.d.ts

@@ -0,0 +1,44 @@
+import type { CoreComputeProvider, DataRow, ProviderExecutionRequest } from './provider';
+interface ClickHouseResultLike {
+    json<T>(): Promise<T>;
+}
+export interface ClickHouseClientLike {
+    query(options: {
+        query: string;
+        format: 'JSONEachRow';
+        query_params: Readonly<Record<string, unknown>>;
+        abort_signal?: AbortSignal;
+    }): Promise<ClickHouseResultLike>;
+    close(): Promise<void>;
+}
+export interface ClickHouseProviderOptions {
+    readonly url?: string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly database?: string;
+    readonly client?: ClickHouseClientLike;
+}
+export declare class ClickHouseProvider implements CoreComputeProvider {
+    readonly kind: "clickhouse";
+    private readonly client;
+    constructor(options?: ClickHouseProviderOptions);
+    quoteIdentifier(identifier: string): string;
+    tableAlias(expression: string, alias: string): string;
+    paginate(sql: string, pageSize: number, offset: number): string;
+    parameter(index: number, value: unknown): string;
+    displayQuery(sql: string, parameters: readonly unknown[]): string;
+    dateBucket(expression: string, level: string): string;
+    dateShift(expression: string, granularity: string, offset: number): string;
+    aggregateFunction(name: string, expression?: string): string;
+    concat(expressions: readonly string[]): string;
+    substring(expression: string, start: number, length: number): string;
+    regex(expression: string, pattern: string, options?: string): string;
+    arrayContains(arrayExpression: string, valueExpression: string): string;
+    expandArray(arrayExpression: string, alias: string, column: string): {
+        joinSql: string;
+        valueExpression: string;
+    };
+    execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    close(): Promise<void>;
+}
+export {};

package/dist/physical/clickhouse-provider.js

@@ -0,0 +1 @@
+import{createClient as i}from"@clickhouse/client";import{displayClickHouseQuery as s}from"./display-query.js";const u=a=>a===null?"Nullable(String)":typeof a=="boolean"?"Bool":typeof a=="number"?"Float64":a instanceof Date?"DateTime64(3)":"String",c=a=>a instanceof Date?a.toISOString().replace("T"," ").replace("Z",""):a;class l{kind="clickhouse";client;constructor(e={}){this.client=e.client??i({url:e.url??"http://localhost:8123",username:e.username??"default",password:e.password??"",database:e.database??"default"})}quoteIdentifier(e){return`\`${e.replaceAll("`","``")}\``}tableAlias(e,r){return`${e} AS ${this.quoteIdentifier(r)}`}paginate(e,r,t){return`${e} LIMIT ${r}${t>0?` OFFSET ${t}`:""}`}parameter(e,r){return`{p${e}:${u(r)}}`}displayQuery(e,r){return s(e,r)}dateBucket(e,r){const n={hour:"toStartOfHour",day:"toStartOfDay",week:"toStartOfWeek",month:"toStartOfMonth",quarter:"toStartOfQuarter",year:"toStartOfYear"}[r];if(!n)throw new Error(`Unsupported ClickHouse date level: ${r}`);return`${n}(${e})`}dateShift(e,r,t){if(!new Set(["second","minute","hour","day","week","month","quarter","year"]).has(r)||!Number.isInteger(t))throw new Error(`Unsupported ClickHouse date shift: ${r}/${t}`);return`dateAdd('${r}', ${t}, ${e})`}aggregateFunction(e,r="*"){if(!/^[A-Za-z][A-Za-z0-9_]*$/.test(e))throw new Error(`Unsupported ClickHouse aggregate function: ${e}`);return`${e.toUpperCase()}(${r})`}concat(e){return`concat(${e.join(", ")})`}substring(e,r,t){return`substring(${e}, ${r}, ${t})`}regex(e,r,t){if(t&&t!=="i")throw new Error(`Unsupported ClickHouse regex options: ${t}`);const n=t==="i"?`concat('(?i)', ${r})`:r;return`match(${e}, ${n})`}arrayContains(e,r){return`has(${e}, ${r})`}expandArray(e,r,t){const n=this.quoteIdentifier(r);return{joinSql:`ARRAY JOIN ${e} AS ${n}`,valueExpression:n}}async execute(e){e.signal?.throwIfAborted();const r=Object.fromEntries(e.parameters.map((n,o)=>[`p${o}`,c(n)]));return(await this.client.query({query:e.sql,format:"JSONEachRow",query_params:r,...e.signal?{abort_signal:e.signal}:{}})).json()}async close(){await this.client.close()}}export{l as ClickHouseProvider};