@narrative.io/data-collaboration-sdk-ts 2.64.1 → 2.66.0

package/build/collaboration-policy/core/sql-builder.js

@@ -0,0 +1,173 @@
+import { buildSelectAlias, resolveAttributeExpression, } from "../utils/sql-helpers";
+import { traversePolicy } from "./policy-traverser";
+import { validatePolicyAgainstDataset } from "./policy-validator";
+function buildAttributeIndexes(attributes) {
+    const byId = new Map();
+    const byName = new Map();
+    for (const attribute of attributes) {
+        byId.set(attribute.id, attribute);
+        byName.set(attribute.name, attribute);
+    }
+    return { byId, byName };
+}
+function getSmallestRefreshSchedule(schedules) {
+    if (schedules.length === 0) {
+        return "@monthly";
+    }
+    // Define the hierarchy for refresh schedules (from smallest to largest)
+    const scheduleHierarchy = {
+        "@once": 0,
+        "@hourly": 1,
+        "@daily": 2,
+        "@weekly": 3,
+        "@monthly": 4,
+    };
+    // Find the schedule with the smallest value (most frequent)
+    let smallestSchedule = "@monthly";
+    let smallestValue = scheduleHierarchy["@monthly"];
+    for (const schedule of schedules) {
+        if (schedule in scheduleHierarchy) {
+            const value = scheduleHierarchy[schedule];
+            if (value < smallestValue) {
+                smallestValue = value;
+                smallestSchedule = schedule;
+            }
+        }
+        else {
+            // If it's a custom cron expression, treat it as the most frequent (smallest)
+            // since we can't easily compare cron expressions
+            return schedule;
+        }
+    }
+    return smallestSchedule;
+}
+function buildPolicySqlUsingIndexes(policies, attributeByName, datasetName) {
+    const globalRequiredAttributePaths = new Map();
+    const policyWhereClauses = [];
+    for (const policy of policies) {
+        const policyRequiredAttributePaths = new Map();
+        const policyWhereClausesSet = new Set();
+        traversePolicy(policy, attributeByName, policyRequiredAttributePaths, policyWhereClausesSet, datasetName);
+        policyWhereClauses.push(Array.from(policyWhereClausesSet));
+        for (const [attributeName, paths] of policyRequiredAttributePaths) {
+            const globalPaths = globalRequiredAttributePaths.get(attributeName) ?? new Set();
+            for (const path of paths) {
+                globalPaths.add(path);
+            }
+            globalRequiredAttributePaths.set(attributeName, globalPaths);
+        }
+    }
+    const selectClauses = new Set();
+    for (const [attributeName, _paths] of globalRequiredAttributePaths) {
+        const attribute = attributeByName.get(attributeName);
+        if (!attribute) {
+            continue;
+        }
+        // Always select the root attribute (without path)
+        const expression = resolveAttributeExpression(attribute, "", // Empty path for root attribute
+        datasetName);
+        const alias = buildSelectAlias(attributeName, "");
+        selectClauses.add(`${expression} AS ${alias}`);
+    }
+    return {
+        select: Array.from(selectClauses),
+        where: policyWhereClauses,
+    };
+}
+export function buildPolicySqlWithValidation(dataset, policies, attributes) {
+    const attributeIndexes = buildAttributeIndexes(attributes);
+    const validPolicies = [];
+    const skippedPolicies = [];
+    const warnings = [];
+    // Validate each policy against the dataset
+    for (const policy of policies) {
+        const validation = validatePolicyAgainstDataset(policy, dataset, attributes);
+        if (validation.isValid) {
+            validPolicies.push(policy);
+        }
+        else {
+            skippedPolicies.push({
+                name: policy.display_name || policy.name,
+                reason: "Missing required attributes or mappings",
+                details: validation.errors,
+            });
+        }
+    }
+    // Check if we have at least one valid policy
+    if (validPolicies.length === 0) {
+        const errorMessage = policies.length === 0
+            ? "No policies provided"
+            : `No policies are compatible with dataset "${dataset.display_name || dataset.name}".`;
+        const details = skippedPolicies.length > 0
+            ? [`Skipped policies: ${skippedPolicies.map((p) => p.name).join(", ")}`]
+            : [];
+        throw new Error(`${errorMessage}\n${details.join("\n")}`);
+    }
+    if (skippedPolicies.length > 0) {
+        warnings.push(`Skipped ${skippedPolicies.length} incompatible policies: ${skippedPolicies.map((p) => p.name).join(", ")}`);
+    }
+    // Build SQL for valid policies
+    const sqlFragments = buildPolicySqlUsingIndexes(validPolicies, attributeIndexes.byName, dataset.name);
+    // Calculate the smallest refresh schedule from applied policies
+    const refreshSchedules = validPolicies
+        .map((p) => p.policy.metadata?.refresh_schedule?.max)
+        .filter((schedule) => schedule !== undefined);
+    const refreshSchedule = getSmallestRefreshSchedule(refreshSchedules);
+    return {
+        ...sqlFragments,
+        appliedPolicies: validPolicies.map((p) => p.name),
+        skippedPolicies,
+        warnings,
+        refresh_schedule: refreshSchedule,
+    };
+}
+/**
+ * Categorizes collaboration policies into matching and non-matching groups based on dataset compatibility.
+ *
+ * This function validates each policy against the provided dataset and attributes to determine
+ * whether the policy can be successfully applied. Policies are categorized as matching if they
+ * have all required attributes available, or non-matching if they're missing required attributes
+ * or mappings.
+ *
+ * @param policies - Array of collaboration policies to categorize
+ * @param dataset - The dataset to validate policies against
+ * @param attributes - Available attributes for validation
+ * @returns Object containing matching policies, non-matching policies, and detailed skip information
+ *
+ * @example
+ * ```typescript
+ * const { matching, nonMatching, skippedDetails } = categorizePolicies(
+ *   allPolicies,
+ *   myDataset,
+ *   availableAttributes
+ * );
+ *
+ * console.log(`${matching.length} policies can be applied`);
+ * console.log(`${nonMatching.length} policies were skipped`);
+ * skippedDetails.forEach(skip => console.log(`Skipped ${skip.name}: ${skip.reason}`));
+ * ```
+ */
+export function categorizePolicies(policies, dataset, attributes) {
+    const matching = [];
+    const nonMatching = [];
+    const skippedDetails = [];
+    for (const policy of policies) {
+        const validation = validatePolicyAgainstDataset(policy, dataset, attributes);
+        if (validation.isValid) {
+            matching.push(policy);
+        }
+        else {
+            nonMatching.push(policy);
+            skippedDetails.push({
+                name: policy.display_name || policy.name,
+                reason: "Missing required attributes or mappings",
+                details: validation.errors,
+            });
+        }
+    }
+    return { matching, nonMatching, skippedDetails };
+}
+export function buildPolicySql(dataset, policies, attributes) {
+    const attributeIndexes = buildAttributeIndexes(attributes);
+    return buildPolicySqlUsingIndexes(policies, attributeIndexes.byName, dataset.name);
+}

package/build/collaboration-policy/core/types.d.ts

@@ -0,0 +1,24 @@
+import type { CollaborationPolicyType } from "../types";
+type PolicyDefinition = CollaborationPolicyType["policy"]["definition"];
+export type StructureNode = PolicyDefinition["structure"];
+export type ExtendedAttributeNode = Extract<StructureNode, {
+    field: unknown;
+}>;
+export type PolicyFilter = NonNullable<PolicyDefinition["filters"]>[number];
+export type PathValue = NonNullable<ExtendedAttributeNode["field"]["additional_required_properties"]>[number];
+export type AttributePathIndex = Map<string, Set<string>>;
+export interface PolicySqlFragments {
+    select: string[];
+    where: string[][];
+}
+export interface PolicyMatchResult extends PolicySqlFragments {
+    appliedPolicies: string[];
+    skippedPolicies: Array<{
+        name: string;
+        reason: string;
+        details: string[];
+    }>;
+    warnings: string[];
+    refresh_schedule: string;
+}
+export {};

package/build/collaboration-policy/core/types.js

@@ -0,0 +1 @@
+export {};

package/build/collaboration-policy/index.d.ts

@@ -0,0 +1,4 @@
+export { buildPolicySql, buildPolicySqlWithValidation, categorizePolicies, } from "./core/sql-builder";
+export type { AttributePathIndex, ExtendedAttributeNode, PathValue, PolicyFilter, PolicyMatchResult, PolicySqlFragments, StructureNode, } from "./core/types";
+export type { CollaborationPolicyInput, CollaborationPolicyType, } from "./types";
+export { buildCollaborationPolicyJsonSchema, CollaborationPolicy, } from "./types";

package/build/collaboration-policy/index.js

@@ -0,0 +1,3 @@
+// Export the main functions
+export { buildPolicySql, buildPolicySqlWithValidation, categorizePolicies, } from "./core/sql-builder";
+export { buildCollaborationPolicyJsonSchema, CollaborationPolicy, } from "./types";

package/build/collaboration-policy/scripts/generate-policy-schema.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/build/collaboration-policy/scripts/generate-policy-schema.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { buildCollaborationPolicyJsonSchema } from "../types";
+const schema = buildCollaborationPolicyJsonSchema();
+console.log(JSON.stringify(schema, null, 2));