sec-edgar-api 0.5.12 → 1.0.1

package/build/examples/xbrl-practical-examples.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Practical examples of working with XBRL relationships using your existing types
+ */
+import type { XbrlInstance, XbrlLinkbase } from '../types';
+/**
+ * Example 1: Extract presentation hierarchy from your XBRL data
+ */
+export declare function extractPresentationHierarchy(presentationLinkbase: XbrlLinkbase): Record<string, ConceptNode>;
+/**
+ * Example 2: Extract calculation relationships
+ */
+export declare function extractCalculationRelationships(calculationLinkbase: XbrlLinkbase): Record<string, CalculationRule>;
+/**
+ * Example 3: Extract dimensional relationships (axis/member mappings)
+ */
+export declare function extractDimensionalRelationships(definitionLinkbase: XbrlLinkbase): Record<string, DimensionStructure>;
+/**
+ * Example 4: Find facts with specific dimensional context
+ */
+export declare function findFactsWithDimensions(instance: XbrlInstance, conceptName: string, dimensionFilters?: {
+    dimension: string;
+    member?: string;
+}[]): {
+    fact: import("../types").XbrlElement;
+    context: import("../types").XbrlContext;
+    dimensions: {
+        dimension: string;
+        member: string;
+    }[];
+}[];
+/**
+ * Example 5: Build a complete concept map with all relationships
+ */
+export declare function buildCompleteConceptMap(linkbases: {
+    presentation: XbrlLinkbase;
+    calculation: XbrlLinkbase;
+    definition: XbrlLinkbase;
+    label: XbrlLinkbase;
+}): Map<string, CompleteConcept>;
+interface ConceptNode {
+    concept: string;
+    children: ConceptChild[];
+    role: string;
+    order: number;
+}
+interface ConceptChild {
+    concept: string;
+    order: number;
+    preferredLabel?: string;
+}
+interface CalculationRule {
+    summationItem: string;
+    contributingItems: CalculationItem[];
+}
+interface CalculationItem {
+    concept: string;
+    weight: number;
+    order: number;
+}
+interface DimensionStructure {
+    concept: string;
+    type: string;
+    dimensions?: string[];
+    domains?: string[];
+    members?: string[];
+}
+interface ConceptLabel {
+    text: string;
+    role: string;
+    lang: string;
+}
+interface CompleteConcept {
+    name: string;
+    labels: ConceptLabel[];
+    presentation: ConceptNode | null;
+    calculation: CalculationRule | null;
+    dimensions: DimensionStructure | null;
+}
+export declare function usageExamples(): {
+    segmentRevenue: {
+        fact: import("../types").XbrlElement;
+        context: import("../types").XbrlContext;
+        dimensions: {
+            dimension: string;
+            member: string;
+        }[];
+    }[];
+    northAmericaRevenue: {
+        fact: import("../types").XbrlElement;
+        context: import("../types").XbrlContext;
+        dimensions: {
+            dimension: string;
+            member: string;
+        }[];
+    }[];
+};
+export {};

package/build/examples/xbrl-practical-examples.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * Practical examples of working with XBRL relationships using your existing types
+ */
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usageExamples = exports.buildCompleteConceptMap = exports.findFactsWithDimensions = exports.extractDimensionalRelationships = exports.extractCalculationRelationships = exports.extractPresentationHierarchy = void 0;
+/**
+ * Example 1: Extract presentation hierarchy from your XBRL data
+ */
+function extractPresentationHierarchy(presentationLinkbase) {
+    var _a;
+    var hierarchy = {};
+    // Process each presentation link (usually one per role/statement)
+    (_a = presentationLinkbase.presentationLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+        var roleUri = link.role || 'default';
+        // Get all concept locators and relationship arcs
+        var locators = (link.loc || []);
+        var arcs = (link.presentationArc || []);
+        // Build concept reference map
+        var conceptMap = new Map();
+        locators.forEach(function (loc) {
+            var concept = extractConceptFromHref(loc.href);
+            conceptMap.set(loc.label, concept);
+        });
+        // Build parent-child relationships
+        arcs.forEach(function (arc) {
+            var parent = conceptMap.get(arc.from);
+            var child = conceptMap.get(arc.to);
+            if (parent && child) {
+                // Initialize parent node if it doesn't exist
+                if (!hierarchy[parent]) {
+                    hierarchy[parent] = {
+                        concept: parent,
+                        children: [],
+                        role: roleUri,
+                        order: 0,
+                    };
+                }
+                // Add child with ordering information
+                hierarchy[parent].children.push({
+                    concept: child,
+                    order: arc.order || 0,
+                    preferredLabel: arc.preferredLabel,
+                });
+                // Sort children by order
+                hierarchy[parent].children.sort(function (a, b) { return a.order - b.order; });
+            }
+        });
+    });
+    return hierarchy;
+}
+exports.extractPresentationHierarchy = extractPresentationHierarchy;
+/**
+ * Example 2: Extract calculation relationships
+ */
+function extractCalculationRelationships(calculationLinkbase) {
+    var _a;
+    var calculations = {};
+    (_a = calculationLinkbase.calculationLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+        var locators = (link.loc || []);
+        var arcs = (link.calculationArc || []);
+        // Build concept reference map
+        var conceptMap = new Map();
+        locators.forEach(function (loc) {
+            var concept = extractConceptFromHref(loc.href);
+            conceptMap.set(loc.label, concept);
+        });
+        // Group arcs by summation item (the 'to' end of the arc)
+        var summationGroups = new Map();
+        arcs.forEach(function (arc) {
+            var summationConcept = conceptMap.get(arc.to);
+            if (summationConcept) {
+                if (!summationGroups.has(summationConcept)) {
+                    summationGroups.set(summationConcept, []);
+                }
+                summationGroups.get(summationConcept).push(arc);
+            }
+        });
+        // Build calculation rules
+        summationGroups.forEach(function (contributingArcs, summationConcept) {
+            calculations[summationConcept] = {
+                summationItem: summationConcept,
+                contributingItems: contributingArcs.map(function (arc) { return ({
+                    concept: conceptMap.get(arc.from) || '',
+                    weight: arc.weight || 1,
+                    order: arc.order || 0,
+                }); }),
+            };
+        });
+    });
+    return calculations;
+}
+exports.extractCalculationRelationships = extractCalculationRelationships;
+/**
+ * Example 3: Extract dimensional relationships (axis/member mappings)
+ */
+function extractDimensionalRelationships(definitionLinkbase) {
+    var _a;
+    var dimensions = {};
+    (_a = definitionLinkbase.definitionLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+        var locators = (link.loc || []);
+        var arcs = (link.definitionArc || []);
+        // Build concept reference map
+        var conceptMap = new Map();
+        locators.forEach(function (loc) {
+            var concept = extractConceptFromHref(loc.href);
+            conceptMap.set(loc.label, concept);
+        });
+        // Process dimensional arcs based on their arcrole
+        arcs.forEach(function (arc) {
+            var fromConcept = conceptMap.get(arc.from);
+            var toConcept = conceptMap.get(arc.to);
+            var arcrole = arc.arcrole || '';
+            if (fromConcept && toConcept) {
+                switch (arcrole) {
+                    case 'http://xbrl.org/int/dim/arcrole/hypercube-dimension':
+                        // Hypercube contains dimension
+                        initializeDimension(dimensions, fromConcept, 'hypercube');
+                        dimensions[fromConcept].dimensions = dimensions[fromConcept].dimensions || [];
+                        dimensions[fromConcept].dimensions.push(toConcept);
+                        break;
+                    case 'http://xbrl.org/int/dim/arcrole/dimension-domain':
+                        // Dimension has domain
+                        initializeDimension(dimensions, fromConcept, 'dimension');
+                        dimensions[fromConcept].domains = dimensions[fromConcept].domains || [];
+                        dimensions[fromConcept].domains.push(toConcept);
+                        break;
+                    case 'http://xbrl.org/int/dim/arcrole/domain-member':
+                        // Domain has member
+                        initializeDimension(dimensions, fromConcept, 'domain');
+                        dimensions[fromConcept].members = dimensions[fromConcept].members || [];
+                        dimensions[fromConcept].members.push(toConcept);
+                        break;
+                }
+            }
+        });
+    });
+    return dimensions;
+}
+exports.extractDimensionalRelationships = extractDimensionalRelationships;
+/**
+ * Example 4: Find facts with specific dimensional context
+ */
+function findFactsWithDimensions(instance, conceptName, dimensionFilters) {
+    var matchingFacts = [];
+    // Filter facts by concept name
+    var conceptFacts = instance.factElements.filter(function (fact) { return fact.name === conceptName; });
+    var _loop_1 = function (fact) {
+        // Get the context for this fact
+        var context = instance.contexts.find(function (ctx) { return ctx.id === fact.contextRef; });
+        if (!context)
+            return "continue";
+        // Check if this fact matches our dimensional filters
+        if (dimensionFilters) {
+            var matchesFilters = dimensionFilters.every(function (filter) {
+                var matchingSegment = context.entity.segment.find(function (seg) { return seg.dimension === filter.dimension; });
+                if (!matchingSegment)
+                    return false;
+                // If specific member is required, check for it
+                if (filter.member && matchingSegment.value !== filter.member) {
+                    return false;
+                }
+                return true;
+            });
+            if (!matchesFilters)
+                return "continue";
+        }
+        matchingFacts.push({
+            fact: fact,
+            context: context,
+            dimensions: context.entity.segment.map(function (seg) { return ({
+                dimension: seg.dimension,
+                member: seg.value,
+            }); }),
+        });
+    };
+    for (var _i = 0, conceptFacts_1 = conceptFacts; _i < conceptFacts_1.length; _i++) {
+        var fact = conceptFacts_1[_i];
+        _loop_1(fact);
+    }
+    return matchingFacts;
+}
+exports.findFactsWithDimensions = findFactsWithDimensions;
+/**
+ * Example 5: Build a complete concept map with all relationships
+ */
+function buildCompleteConceptMap(linkbases) {
+    var conceptMap = new Map();
+    // Extract all relationships
+    var presentationHierarchy = extractPresentationHierarchy(linkbases.presentation);
+    var calculationRelationships = extractCalculationRelationships(linkbases.calculation);
+    var dimensionalRelationships = extractDimensionalRelationships(linkbases.definition);
+    var labels = extractLabels(linkbases.label);
+    // Combine all concepts
+    var allConcepts = new Set(__spreadArray(__spreadArray(__spreadArray(__spreadArray([], Object.keys(presentationHierarchy), true), Object.keys(calculationRelationships), true), Object.keys(dimensionalRelationships), true), Object.keys(labels), true));
+    // Build complete concept entries
+    allConcepts.forEach(function (concept) {
+        conceptMap.set(concept, {
+            name: concept,
+            labels: labels[concept] || [],
+            presentation: presentationHierarchy[concept] || null,
+            calculation: calculationRelationships[concept] || null,
+            dimensions: dimensionalRelationships[concept] || null,
+        });
+    });
+    return conceptMap;
+}
+exports.buildCompleteConceptMap = buildCompleteConceptMap;
+// Helper functions and types
+function extractConceptFromHref(href) {
+    var match = href.match(/#(.+)$/);
+    return match ? match[1] : '';
+}
+function initializeDimension(dimensions, concept, type) {
+    if (!dimensions[concept]) {
+        dimensions[concept] = {
+            concept: concept,
+            type: type,
+            dimensions: [],
+            domains: [],
+            members: [],
+        };
+    }
+}
+function extractLabels(labelLinkbase) {
+    var _a;
+    var labels = {};
+    (_a = labelLinkbase.labelLink) === null || _a === void 0 ? void 0 : _a.forEach(function (link) {
+        var locators = (link.loc || []);
+        var arcs = (link.labelArc || []);
+        var labelResources = link.label || [];
+        // Build concept reference map
+        var conceptMap = new Map();
+        locators.forEach(function (loc) {
+            var concept = extractConceptFromHref(loc.href);
+            conceptMap.set(loc.label, concept);
+        });
+        // Connect labels to concepts
+        arcs.forEach(function (arc) {
+            var concept = conceptMap.get(arc.from);
+            var labelResource = labelResources.find(function (r) { return r.label === arc.to; });
+            if (concept && labelResource) {
+                labels[concept] = labels[concept] || [];
+                labels[concept].push({
+                    text: labelResource.text || '',
+                    role: labelResource.role || '',
+                    lang: labelResource.lang || 'en',
+                });
+            }
+        });
+    });
+    return labels;
+}
+// Usage examples:
+function usageExamples() {
+    // Example: Get all revenue facts broken down by segment
+    var segmentRevenue = findFactsWithDimensions({}, // Your XBRL instance
+    'us-gaap:Revenues', [{ dimension: 'us-gaap:SegmentDomain' }]);
+    // Example: Get specific segment revenue
+    var northAmericaRevenue = findFactsWithDimensions({}, 'us-gaap:Revenues', [
+        {
+            dimension: 'us-gaap:SegmentDomain',
+            member: 'us-gaap:NorthAmericaSegmentMember',
+        },
+    ]);
+    return { segmentRevenue: segmentRevenue, northAmericaRevenue: northAmericaRevenue };
+}
+exports.usageExamples = usageExamples;

package/build/examples/xbrl-relationships.d.ts

@@ -0,0 +1,145 @@
+import type { XbrlInstance, XbrlLinkbase, XbrlSchema } from '../types';
+export declare class XbrlRelationshipBuilder {
+    private instance;
+    private schema;
+    private presentationLinkbase;
+    private calculationLinkbase;
+    private definitionLinkbase;
+    private labelLinkbase;
+    constructor(data: {
+        instance: XbrlInstance;
+        schema: XbrlSchema;
+        presentationLinkbase: XbrlLinkbase;
+        calculationLinkbase: XbrlLinkbase;
+        definitionLinkbase: XbrlLinkbase;
+        labelLinkbase: XbrlLinkbase;
+    });
+    /**
+     * 1. PRESENTATION LINKBASE - Defines hierarchical structure
+     * Shows how concepts are organized in financial statements
+     */
+    buildPresentationHierarchy(): Record<string, ConceptHierarchy>;
+    /**
+     * 2. CALCULATION LINKBASE - Defines mathematical relationships
+     * Shows how concepts add up to totals
+     */
+    buildCalculationRelationships(): Record<string, CalculationRelationship>;
+    /**
+     * 3. DEFINITION LINKBASE - Defines dimensional relationships
+     * Shows axis, members, domains, and hypercubes
+     */
+    buildDimensionalRelationships(): Record<string, DimensionalRelationship>;
+    /**
+     * 4. LABEL LINKBASE - Provides human-readable labels
+     * Maps concepts to their display labels
+     */
+    buildLabelMappings(): Record<string, ConceptLabel[]>;
+    /**
+     * 5. RELATING FACTS TO DIMENSIONS
+     * Shows how actual data values relate to dimensional context
+     */
+    buildFactDimensionalMappings(): FactDimensionalMapping[];
+    /**
+     * 6. COMPREHENSIVE TAXONOMY MAPPING
+     * Combines all relationships into a unified structure
+     */
+    buildComprehensiveTaxonomyMap(): {
+        presentation: Record<string, ConceptHierarchy>;
+        calculations: Record<string, CalculationRelationship>;
+        dimensions: Record<string, DimensionalRelationship>;
+        labels: Record<string, ConceptLabel[]>;
+        factMappings: FactDimensionalMapping[];
+        getConceptChildren: (concept: string) => ConceptChild[];
+        getConceptCalculation: (concept: string) => CalculationRelationship;
+        getConceptLabels: (concept: string) => ConceptLabel[];
+        getFactsForConcept: (concept: string) => FactDimensionalMapping[];
+        getDimensionsForConcept: (concept: string) => DimensionalRelationship;
+    };
+    private getLocators;
+    private getPresentationArcs;
+    private getCalculationArcs;
+    private getDefinitionArcs;
+    private getLabelArcs;
+    private getLabelResources;
+    private getConceptFromLocator;
+    private addHypercubeDimension;
+    private addDimensionDomain;
+    private addDomainMember;
+    private addAllRelationship;
+}
+interface ConceptHierarchy {
+    concept: string;
+    children: ConceptChild[];
+    order: number;
+    role: string;
+}
+interface ConceptChild {
+    concept: string;
+    order: number;
+    preferredLabel?: string;
+}
+interface CalculationRelationship {
+    summationItem: string;
+    contributingItems: CalculationItem[];
+}
+interface CalculationItem {
+    concept: string;
+    weight: number;
+    order: number;
+}
+interface DimensionalRelationship {
+    type: 'hypercube' | 'dimension' | 'domain' | 'member';
+    concept: string;
+    dimensions?: DimensionalItem[];
+    domains?: DimensionalItem[];
+    members?: DimensionalItem[];
+    all?: DimensionalItem[];
+}
+interface DimensionalItem {
+    concept: string;
+    type: string;
+}
+interface ConceptLabel {
+    text: string;
+    role: string;
+    lang: string;
+}
+interface FactDimensionalMapping {
+    factName: string;
+    value: string;
+    unit: string;
+    context: DimensionalContext;
+    contextRef: string;
+}
+interface DimensionalContext {
+    entity: string;
+    period: {
+        startDate?: string;
+        endDate?: string;
+        instant?: string;
+    };
+    dimensions: {
+        dimension: string;
+        member: string;
+    }[];
+}
+export declare function exampleUsage(xbrlData: {
+    instance: XbrlInstance;
+    schema: XbrlSchema;
+    presentationLinkbase: XbrlLinkbase;
+    calculationLinkbase: XbrlLinkbase;
+    definitionLinkbase: XbrlLinkbase;
+    labelLinkbase: XbrlLinkbase;
+}): {
+    presentation: Record<string, ConceptHierarchy>;
+    calculations: Record<string, CalculationRelationship>;
+    dimensions: Record<string, DimensionalRelationship>;
+    labels: Record<string, ConceptLabel[]>;
+    factMappings: FactDimensionalMapping[];
+    getConceptChildren: (concept: string) => ConceptChild[];
+    getConceptCalculation: (concept: string) => CalculationRelationship;
+    getConceptLabels: (concept: string) => ConceptLabel[];
+    getFactsForConcept: (concept: string) => FactDimensionalMapping[];
+    getDimensionsForConcept: (concept: string) => DimensionalRelationship;
+};
+export {};