meadow-integration 1.0.1 → 1.0.4

package/examples/Example-001-CSV-Check.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Example 001: CSV Check
+# ---------------------
+# Analyze a CSV file to get statistics about its structure and contents.
+# This is typically the first step when working with a new data set.
+#
+# Usage:  ./Example-001-CSV-Check.sh
+# Output: examples/output/books-stats.json
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI="${SCRIPT_DIR}/../source/cli/Meadow-Integration-CLI-Run.js"
+DATA_DIR="${SCRIPT_DIR}/../docs/examples/data"
+OUTPUT_DIR="${SCRIPT_DIR}/output"
+
+echo "=== Example 001: CSV Check ==="
+echo ""
+echo "Running csvcheck on books.csv to gather statistics..."
+echo ""
+
+node "${CLI}" csvcheck "${DATA_DIR}/books.csv" \
+	-o "${OUTPUT_DIR}/books-stats.json"
+
+echo ""
+echo "Statistics written to: examples/output/books-stats.json"
+echo ""
+echo "You can examine the output file to see:"
+echo "  - Row and column counts"
+echo "  - Column headers"
+echo "  - Per-column statistics (empty counts, numeric counts, first/last values)"

package/examples/Example-002-CSV-Transform-Implicit.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Example 002: CSV Transform (Implicit Configuration)
+# ----------------------------------------------------
+# Transform a CSV file into a comprehension using auto-detected settings.
+# When no mapping file or explicit options are provided, meadow-integration
+# will infer the entity name from the filename and create a 1:1 column mapping.
+#
+# Usage:  ./Example-002-CSV-Transform-Implicit.sh
+# Output: examples/output/books-implicit-comprehension.json
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI="${SCRIPT_DIR}/../source/cli/Meadow-Integration-CLI-Run.js"
+DATA_DIR="${SCRIPT_DIR}/../docs/examples/data"
+OUTPUT_DIR="${SCRIPT_DIR}/output"
+
+echo "=== Example 002: CSV Transform (Implicit Configuration) ==="
+echo ""
+echo "Transforming books.csv into a comprehension with auto-detected settings..."
+echo "(Entity name and GUID will be derived from the file name and first column)"
+echo ""
+
+node "${CLI}" csvtransform "${DATA_DIR}/books.csv" \
+	-o "${OUTPUT_DIR}/books-implicit-comprehension.json"
+
+echo ""
+echo "Comprehension written to: examples/output/books-implicit-comprehension.json"
+echo ""
+echo "The implicit configuration:"
+echo "  - Entity name derived from the CSV filename"
+echo "  - GUID generated from the first column value"
+echo "  - All columns mapped 1:1 to comprehension fields"

package/examples/Example-003-CSV-Transform-CLI-Options.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Example 003: CSV Transform (CLI Options)
+# -----------------------------------------
+# Transform a CSV file into a comprehension using command-line options to
+# control the entity name, GUID template, and column mappings.
+#
+# This gives you explicit control over:
+#   -e  Entity name (what this data represents)
+#   -n  GUID column name in the output
+#   -g  GUID template (Pict template using column values)
+#
+# Usage:  ./Example-003-CSV-Transform-CLI-Options.sh
+# Output: examples/output/books-cli-comprehension.json
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI="${SCRIPT_DIR}/../source/cli/Meadow-Integration-CLI-Run.js"
+DATA_DIR="${SCRIPT_DIR}/../docs/examples/data"
+OUTPUT_DIR="${SCRIPT_DIR}/output"
+
+echo "=== Example 003: CSV Transform (CLI Options) ==="
+echo ""
+echo "Transforming books.csv with explicit CLI options..."
+echo "  Entity: Book"
+echo "  GUID Column: GUIDBook"
+echo "  GUID Template: Book_{~D:Record.id~}"
+echo ""
+
+node "${CLI}" csvtransform "${DATA_DIR}/books.csv" \
+	-e "Book" \
+	-n "GUIDBook" \
+	-g "Book_{~D:Record.id~}" \
+	-o "${OUTPUT_DIR}/books-cli-comprehension.json"
+
+echo ""
+echo "Comprehension written to: examples/output/books-cli-comprehension.json"
+echo ""
+echo "Each record in the comprehension now has:"
+echo "  - A GUIDBook field with values like 'Book_1', 'Book_2', etc."
+echo "  - All original CSV columns as additional fields"

package/examples/Example-004-CSV-Transform-Mapping-File.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Example 004: CSV Transform (Mapping File)
+# ------------------------------------------
+# Transform a CSV file using a mapping file for precise control over
+# which columns are extracted and how they are named.
+#
+# The mapping file (mapping_books_Book.json) defines:
+#   Entity       - The entity name
+#   GUIDTemplate - How to generate unique IDs
+#   Mappings     - Column name -> Pict template pairs
+#
+# This is the recommended approach for production data integration.
+#
+# Usage:  ./Example-004-CSV-Transform-Mapping-File.sh
+# Output: examples/output/books-mapped-comprehension.json
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI="${SCRIPT_DIR}/../source/cli/Meadow-Integration-CLI-Run.js"
+DATA_DIR="${SCRIPT_DIR}/../docs/examples/data"
+MAPPING_DIR="${SCRIPT_DIR}/../docs/examples/bookstore"
+OUTPUT_DIR="${SCRIPT_DIR}/output"
+
+echo "=== Example 004: CSV Transform (Mapping File) ==="
+echo ""
+echo "Transforming books.csv using mapping_books_Book.json..."
+echo ""
+echo "Mapping file contents:"
+cat "${MAPPING_DIR}/mapping_books_Book.json"
+echo ""
+echo ""
+
+node "${CLI}" csvtransform "${DATA_DIR}/books.csv" \
+	-m "${MAPPING_DIR}/mapping_books_Book.json" \
+	-o "${OUTPUT_DIR}/books-mapped-comprehension.json"
+
+echo ""
+echo "Comprehension written to: examples/output/books-mapped-comprehension.json"
+echo ""
+echo "Notice the output only contains the mapped fields:"
+echo "  Title, Language, PublicationYear, ISBN, Genre, Type, ImageURL"
+echo "  (not all 23 original CSV columns)"

package/examples/Example-005-Multi-Entity-Bookstore.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Example 005: Multi-Entity Bookstore Integration
+# -------------------------------------------------
+# Build a complete multi-entity comprehension from a single CSV file.
+# This demonstrates how one CSV can produce multiple entity types
+# using different mapping files.
+#
+# The books.csv file contains book data with authors in a single column.
+# We use three mapping files to extract:
+#   1. Book      - Basic book information
+#   2. Author    - Unique author names (using Solvers to split comma-separated authors)
+#   3. BookAuthorJoin - Many-to-many relationship between books and authors
+#
+# Each transform pass adds its entity to the same comprehension file
+# by using the -i flag to pass in the existing comprehension.
+#
+# Usage:  ./Example-005-Multi-Entity-Bookstore.sh
+# Output: examples/output/bookstore-comprehension.json
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI="${SCRIPT_DIR}/../source/cli/Meadow-Integration-CLI-Run.js"
+DATA_DIR="${SCRIPT_DIR}/../docs/examples/data"
+MAPPING_DIR="${SCRIPT_DIR}/../docs/examples/bookstore"
+OUTPUT_DIR="${SCRIPT_DIR}/output"
+COMP_FILE="${OUTPUT_DIR}/bookstore-comprehension.json"
+
+echo "=== Example 005: Multi-Entity Bookstore ==="
+echo ""
+
+# Step 1: Create the Book entity comprehension
+echo "--- Step 1: Creating Book entities ---"
+node "${CLI}" csvtransform "${DATA_DIR}/books.csv" \
+	-m "${MAPPING_DIR}/mapping_books_Book.json" \
+	-o "${COMP_FILE}"
+echo ""
+
+# Step 2: Add the Author entities to the same comprehension
+echo "--- Step 2: Adding Author entities ---"
+echo "(Uses Solvers to split comma-separated author names into individual records)"
+node "${CLI}" csvtransform "${DATA_DIR}/books.csv" \
+	-m "${MAPPING_DIR}/mapping_books_Author.json" \
+	-i "${COMP_FILE}" \
+	-o "${COMP_FILE}"
+echo ""
+
+# Step 3: Add the BookAuthorJoin entities to complete the comprehension
+echo "--- Step 3: Adding BookAuthorJoin entities ---"
+echo "(Creates a join record for every book-author pair)"
+node "${CLI}" csvtransform "${DATA_DIR}/books.csv" \
+	-m "${MAPPING_DIR}/mapping_books_BookAuthorJoin.json" \
+	-i "${COMP_FILE}" \
+	-o "${COMP_FILE}"
+echo ""
+
+echo "Complete bookstore comprehension written to: examples/output/bookstore-comprehension.json"
+echo ""
+echo "The comprehension contains three entity types:"
+echo "  - Book: One record per book"
+echo "  - Author: One record per unique author"
+echo "  - BookAuthorJoin: One record per book-author relationship"

package/examples/Example-006-Multi-CSV-Intersect.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# Example 006: Multi-CSV Intersect (Seattle Neighborhoods)
+# ---------------------------------------------------------
+# Merge data from multiple CSV files that share a common key.
+# This is a common scenario when data about the same entities
+# comes from different sources or different tables.
+#
+# The Seattle neighborhood data has three CSV files:
+#   - housing_characteristics_Neighborhoods.csv
+#   - housing_costs_Neighborhoods.csv
+#   - race_ethnicity_Neighborhoods.csv
+#
+# All three share a "Neighborhood Name" column.  We transform
+# each into a comprehension keyed on that column, then use
+# comprehensionintersect to merge them into one unified dataset.
+#
+# Usage:  ./Example-006-Multi-CSV-Intersect.sh
+# Output: examples/output/seattle-merged.json
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI="${SCRIPT_DIR}/../source/cli/Meadow-Integration-CLI-Run.js"
+DATA_DIR="${SCRIPT_DIR}/../docs/examples/data/seattle_neighborhoods"
+OUTPUT_DIR="${SCRIPT_DIR}/output"
+
+echo "=== Example 006: Multi-CSV Intersect (Seattle Neighborhoods) ==="
+echo ""
+
+# Step 1: Transform housing characteristics
+echo "--- Step 1: Transform housing characteristics CSV ---"
+node "${CLI}" csvtransform "${DATA_DIR}/housing_characteristics_Neighborhoods.csv" \
+	-e "Neighborhood" \
+	-n "GUIDNeighborhood" \
+	-g "{~D:Record.Neighborhood Name~}" \
+	-o "${OUTPUT_DIR}/seattle-housing-chars.json"
+echo ""
+
+# Step 2: Transform housing costs
+echo "--- Step 2: Transform housing costs CSV ---"
+node "${CLI}" csvtransform "${DATA_DIR}/housing_costs_Neighborhoods.csv" \
+	-e "Neighborhood" \
+	-n "GUIDNeighborhood" \
+	-g "{~D:Record.Neighborhood Name~}" \
+	-o "${OUTPUT_DIR}/seattle-housing-costs.json"
+echo ""
+
+# Step 3: Transform race and ethnicity
+echo "--- Step 3: Transform race and ethnicity CSV ---"
+node "${CLI}" csvtransform "${DATA_DIR}/race_ethnicity_Neighborhoods.csv" \
+	-e "Neighborhood" \
+	-n "GUIDNeighborhood" \
+	-g "{~D:Record.Neighborhood Name~}" \
+	-o "${OUTPUT_DIR}/seattle-race-ethnicity.json"
+echo ""
+
+# Step 4: Merge housing chars + housing costs
+echo "--- Step 4: Intersect housing characteristics with housing costs ---"
+node "${CLI}" comprehensionintersect "${OUTPUT_DIR}/seattle-housing-chars.json" \
+	-i "${OUTPUT_DIR}/seattle-housing-costs.json" \
+	-e "Neighborhood" \
+	-o "${OUTPUT_DIR}/seattle-merged.json"
+echo ""
+
+# Step 5: Merge the result with race/ethnicity data
+echo "--- Step 5: Intersect merged data with race/ethnicity ---"
+node "${CLI}" comprehensionintersect "${OUTPUT_DIR}/seattle-merged.json" \
+	-i "${OUTPUT_DIR}/seattle-race-ethnicity.json" \
+	-e "Neighborhood" \
+	-o "${OUTPUT_DIR}/seattle-merged.json"
+echo ""
+
+echo "Merged comprehension written to: examples/output/seattle-merged.json"
+echo ""
+echo "Each neighborhood record now contains columns from all three source CSVs,"
+echo "merged by matching Neighborhood Name."

package/examples/Example-007-Comprehension-To-Array.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Example 007: Comprehension to Array
+# -------------------------------------
+# Convert an object-keyed comprehension into a JSON array.
+# Comprehensions store records as { GUID: record } objects for
+# fast lookup and merging.  But sometimes you need a plain array,
+# for instance to feed into a UI table or export to CSV.
+#
+# This example first creates a Book comprehension, then converts
+# it from the object format to an array format.
+#
+# Usage:  ./Example-007-Comprehension-To-Array.sh
+# Output: examples/output/books-array.json
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI="${SCRIPT_DIR}/../source/cli/Meadow-Integration-CLI-Run.js"
+DATA_DIR="${SCRIPT_DIR}/../docs/examples/data"
+MAPPING_DIR="${SCRIPT_DIR}/../docs/examples/bookstore"
+OUTPUT_DIR="${SCRIPT_DIR}/output"
+
+echo "=== Example 007: Comprehension to Array ==="
+echo ""
+
+# Step 1: Create a Book comprehension
+echo "--- Step 1: Create a Book comprehension ---"
+node "${CLI}" csvtransform "${DATA_DIR}/books.csv" \
+	-m "${MAPPING_DIR}/mapping_books_Book.json" \
+	-o "${OUTPUT_DIR}/books-for-array.json"
+echo ""
+
+# Step 2: Convert from object comprehension to array
+echo "--- Step 2: Convert to array format ---"
+node "${CLI}" comprehensionarray "${OUTPUT_DIR}/books-for-array.json" \
+	-e "Book" \
+	-o "${OUTPUT_DIR}/books-array.json"
+echo ""
+
+echo "Array comprehension written to: examples/output/books-array.json"
+echo ""
+echo "Object format:  { 'Book': { 'Book_1': {...}, 'Book_2': {...} } }"
+echo "Array format:   [ {...}, {...}, ... ]"

package/examples/Example-008-Comprehension-To-CSV.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Example 008: Comprehension to CSV
+# ------------------------------------
+# Export a comprehension back to CSV format.  This is useful for:
+#   - Sharing data with tools that expect CSV input
+#   - Reviewing merged/transformed data in a spreadsheet
+#   - Round-tripping data through the integration pipeline
+#
+# Workflow:
+#   1. CSV -> Comprehension (csvtransform with mapping file)
+#   2. Object Comprehension -> Array (comprehensionarray)
+#   3. Array -> CSV (objectarraytocsv)
+#
+# Usage:  ./Example-008-Comprehension-To-CSV.sh
+# Output: examples/output/books-export.csv
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI="${SCRIPT_DIR}/../source/cli/Meadow-Integration-CLI-Run.js"
+DATA_DIR="${SCRIPT_DIR}/../docs/examples/data"
+MAPPING_DIR="${SCRIPT_DIR}/../docs/examples/bookstore"
+OUTPUT_DIR="${SCRIPT_DIR}/output"
+
+echo "=== Example 008: Comprehension to CSV ==="
+echo ""
+
+# Step 1: Create a Book comprehension (object format)
+echo "--- Step 1: Create a Book comprehension ---"
+node "${CLI}" csvtransform "${DATA_DIR}/books.csv" \
+	-m "${MAPPING_DIR}/mapping_books_Book.json" \
+	-o "${OUTPUT_DIR}/books-for-csv.json"
+echo ""
+
+# Step 2: Convert to array format (objectarraytocsv needs an array)
+echo "--- Step 2: Convert object comprehension to array ---"
+node "${CLI}" comprehensionarray "${OUTPUT_DIR}/books-for-csv.json" \
+	-e "Book" \
+	-o "${OUTPUT_DIR}/books-array-for-csv.json"
+echo ""
+
+# Step 3: Export array to CSV
+# objectarraytocsv reads a plain JSON array and writes CSV
+echo "--- Step 3: Export array to CSV ---"
+node "${CLI}" objectarraytocsv "${OUTPUT_DIR}/books-array-for-csv.json" \
+	-o "${OUTPUT_DIR}/books-export.csv"
+echo ""
+
+LINECOUNT=$(wc -l < "${OUTPUT_DIR}/books-export.csv")
+echo "CSV exported to: examples/output/books-export.csv (${LINECOUNT} lines)"
+echo ""
+echo "First 3 lines of output:"
+head -3 "${OUTPUT_DIR}/books-export.csv"

package/examples/Example-009-JSON-Array-Transform.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Example 009: JSON Array Transform
+# -----------------------------------
+# Transform a JSON array file into a comprehension.
+# This works just like csvtransform but reads from a JSON array
+# instead of a CSV file.
+#
+# This example first creates a JSON array from book data,
+# then re-transforms it using the jsonarraytransform command.
+#
+# Usage:  ./Example-009-JSON-Array-Transform.sh
+# Output: examples/output/books-from-json.json
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI="${SCRIPT_DIR}/../source/cli/Meadow-Integration-CLI-Run.js"
+DATA_DIR="${SCRIPT_DIR}/../docs/examples/data"
+MAPPING_DIR="${SCRIPT_DIR}/../docs/examples/bookstore"
+OUTPUT_DIR="${SCRIPT_DIR}/output"
+
+echo "=== Example 009: JSON Array Transform ==="
+echo ""
+
+# Step 1: First create a JSON array from the books CSV
+echo "--- Step 1: Create a source JSON array ---"
+node "${CLI}" csvtransform "${DATA_DIR}/books.csv" \
+	-e "Book" -n "GUIDBook" -g "Book_{~D:Record.id~}" \
+	-o "${OUTPUT_DIR}/books-object-source.json"
+
+node "${CLI}" comprehensionarray "${OUTPUT_DIR}/books-object-source.json" \
+	-e "Book" \
+	-o "${OUTPUT_DIR}/books-json-array-source.json"
+echo ""
+
+# Step 2: Transform the JSON array into a new comprehension with mapping
+echo "--- Step 2: Transform JSON array with mapping file ---"
+node "${CLI}" jsonarraytransform "${OUTPUT_DIR}/books-json-array-source.json" \
+	-m "${MAPPING_DIR}/mapping_books_Book.json" \
+	-o "${OUTPUT_DIR}/books-from-json.json"
+echo ""
+
+echo "Comprehension from JSON array written to: examples/output/books-from-json.json"
+echo ""
+echo "jsonarraytransform supports the same options as csvtransform:"
+echo "  -e, -n, -g, -c for CLI options"
+echo "  -m for mapping files"
+echo "  -i for incoming comprehension merging"

package/examples/Example-010-Programmatic-API.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Example 010: Programmatic API
+ * ------------------------------
+ * Use meadow-integration services directly in your own Node.js code.
+ * This demonstrates using the TabularCheck and TabularTransform services
+ * without the CLI, which is useful when integrating into larger applications.
+ *
+ * Usage:  node Example-010-Programmatic-API.js
+ */
+const libPict = require('pict');
+const libFS = require('fs');
+const libPath = require('path');
+
+// Initialize pict (which extends fable with template parsing)
+// The TabularTransform service uses parseTemplate, which requires pict.
+let _Fable = new libPict({ LogLevel: 3 });
+
+// Instantiate necessary services
+_Fable.instantiateServiceProvider('CSVParser');
+
+// Load and register the TabularCheck service
+const libTabularCheck = require('../source/services/tabular/Service-TabularCheck.js');
+_Fable.addAndInstantiateServiceType('MeadowIntegrationTabularCheck', libTabularCheck);
+
+// Load and register the TabularTransform service
+const libTabularTransform = require('../source/services/tabular/Service-TabularTransform.js');
+_Fable.addAndInstantiateServiceType('MeadowIntegrationTabularTransform', libTabularTransform);
+
+// ---- Part 1: Collecting Statistics ----
+console.log('=== Part 1: TabularCheck - Collecting Statistics ===\n');
+
+let tmpStatistics = _Fable.MeadowIntegrationTabularCheck.newStatisticsObject('ProgrammaticBooks');
+
+// Read and parse a few lines from the CSV
+let tmpCSVContent = libFS.readFileSync(
+	libPath.join(__dirname, '..', 'docs', 'examples', 'data', 'books.csv'),
+	'utf8'
+);
+let tmpLines = tmpCSVContent.split('\n');
+
+// Parse each line and collect statistics (first 50 rows for quick demo)
+let tmpRecordCount = 0;
+for (let i = 0; i < Math.min(tmpLines.length, 50); i++)
+{
+	let tmpRecord = _Fable.CSVParser.parseCSVLine(tmpLines[i]);
+	if (tmpRecord)
+	{
+		_Fable.MeadowIntegrationTabularCheck.collectStatistics(tmpRecord, tmpStatistics);
+		tmpRecordCount++;
+	}
+}
+
+console.log(`Analyzed ${tmpStatistics.RowCount} rows with ${tmpStatistics.ColumnCount} columns`);
+console.log(`Headers: ${tmpStatistics.Headers.join(', ')}`);
+console.log('');
+
+// Show a few column statistics
+let tmpColumnKeys = Object.keys(tmpStatistics.ColumnStatistics);
+for (let i = 0; i < Math.min(tmpColumnKeys.length, 5); i++)
+{
+	let tmpKey = tmpColumnKeys[i];
+	let tmpStats = tmpStatistics.ColumnStatistics[tmpKey];
+	console.log(`  [${tmpKey}]: ${tmpStats.Count} values, ${tmpStats.EmptyCount} empty, ${tmpStats.NumericCount} numeric`);
+}
+
+// ---- Part 2: Transforming Records ----
+console.log('\n=== Part 2: TabularTransform - Creating Comprehensions ===\n');
+
+// Set up a mapping outcome
+let tmpMappingOutcome = _Fable.MeadowIntegrationTabularTransform.newMappingOutcomeObject();
+
+// Provide explicit configuration (same as a mapping file)
+tmpMappingOutcome.ExplicitConfiguration = {
+	"Entity": "Book",
+	"GUIDTemplate": "Book_{~D:Record.id~}",
+	"Mappings": {
+		"Title": "{~D:Record.title~}",
+		"Language": "{~D:Record.language_code~}",
+		"ISBN": "{~D:Record.isbn~}",
+		"Genre": "Unknown",
+		"Type": "Book"
+	}
+};
+
+// Create an implicit config from the first record
+let tmpFirstRecord = _Fable.CSVParser.parseCSVLine(tmpLines[1]);
+tmpMappingOutcome.ImplicitConfiguration = _Fable.MeadowIntegrationTabularTransform.generateMappingConfigurationPrototype('books.csv', tmpFirstRecord);
+
+// Merge configurations
+tmpMappingOutcome.Configuration = Object.assign({},
+	tmpMappingOutcome.ImplicitConfiguration,
+	tmpMappingOutcome.ExplicitConfiguration
+);
+tmpMappingOutcome.Configuration.GUIDName = `GUID${tmpMappingOutcome.Configuration.Entity}`;
+tmpMappingOutcome.Comprehension[tmpMappingOutcome.Configuration.Entity] = {};
+
+// Transform records into the comprehension
+for (let i = 1; i < Math.min(tmpLines.length, 11); i++)
+{
+	let tmpRecord = _Fable.CSVParser.parseCSVLine(tmpLines[i]);
+	if (tmpRecord)
+	{
+		_Fable.MeadowIntegrationTabularTransform.addRecordToComprehension(
+			tmpRecord, tmpMappingOutcome);
+	}
+}
+
+// Show results
+let tmpBookKeys = Object.keys(tmpMappingOutcome.Comprehension.Book);
+console.log(`Created ${tmpBookKeys.length} Book records in comprehension`);
+console.log('');
+
+// Print first 3 records
+for (let i = 0; i < Math.min(tmpBookKeys.length, 3); i++)
+{
+	let tmpBook = tmpMappingOutcome.Comprehension.Book[tmpBookKeys[i]];
+	console.log(`  ${tmpBook.GUIDBook}: ${tmpBook.Title} (${tmpBook.Language})`);
+}
+
+// ---- Part 3: GUIDMap Service ----
+console.log('\n=== Part 3: GUIDMap - Tracking External System IDs ===\n');
+
+const libGUIDMap = require('../source/Meadow-Service-Integration-GUIDMap.js');
+_Fable.addAndInstantiateServiceType('MeadowGUIDMap', libGUIDMap);
+
+// Map external GUIDs to Meadow GUIDs and IDs
+_Fable.MeadowGUIDMap.mapGUIDToID('Book', 'Book_1', 101);
+_Fable.MeadowGUIDMap.mapGUIDToID('Book', 'Book_2', 102);
+_Fable.MeadowGUIDMap.mapExternalGUIDtoMeadowGUID('Book', 'LEGACY-ISBN-439023483', 'Book_1');
+
+// Look up in both directions
+console.log(`  GUID 'Book_1' -> ID: ${_Fable.MeadowGUIDMap.getIDFromGUID('Book', 'Book_1')}`);
+console.log(`  ID 101 -> GUID: ${_Fable.MeadowGUIDMap.getGUIDFromID('Book', 101)}`);
+console.log(`  External 'LEGACY-ISBN-439023483' -> Meadow GUID: ${_Fable.MeadowGUIDMap.getMeadowGUIDFromExternalGUID('Book', 'LEGACY-ISBN-439023483')}`);
+console.log(`  External 'LEGACY-ISBN-439023483' -> Meadow ID: ${_Fable.MeadowGUIDMap.getMeadowIDFromExternalGUID('Book', 'LEGACY-ISBN-439023483')}`);
+
+console.log('\nDone!');

package/examples/README.md

@@ -0,0 +1,44 @@
+# Meadow Integration Examples
+
+Runnable examples demonstrating meadow-integration features.  Each example can be run from this directory and writes output to the `output/` folder.
+
+## Prerequisites
+
+```shell
+cd ..
+npm install
+```
+
+## Examples
+
+| # | File | Description |
+|---|------|-------------|
+| 001 | `Example-001-CSV-Check.sh` | Analyze a CSV file structure and column statistics |
+| 002 | `Example-002-CSV-Transform-Implicit.sh` | Auto-detect entity and columns from a CSV |
+| 003 | `Example-003-CSV-Transform-CLI-Options.sh` | Use CLI flags to control entity name and GUID template |
+| 004 | `Example-004-CSV-Transform-Mapping-File.sh` | Use a JSON mapping file for precise column control |
+| 005 | `Example-005-Multi-Entity-Bookstore.sh` | Build Book, Author, and BookAuthorJoin from one CSV |
+| 006 | `Example-006-Multi-CSV-Intersect.sh` | Merge three Seattle neighborhood CSVs by common key |
+| 007 | `Example-007-Comprehension-To-Array.sh` | Convert object-keyed comprehension to a JSON array |
+| 008 | `Example-008-Comprehension-To-CSV.sh` | Full round-trip: CSV to comprehension back to CSV |
+| 009 | `Example-009-JSON-Array-Transform.sh` | Transform a JSON array file into a comprehension |
+| 010 | `Example-010-Programmatic-API.js` | Use the services directly in Node.js code |
+
+## Running
+
+```shell
+# Run a single example
+./Example-001-CSV-Check.sh
+
+# Run the Node.js programmatic example
+node Example-010-Programmatic-API.js
+```
+
+Output files are written to `output/` and ignored by git.
+
+## Data Sources
+
+Examples use data from `../docs/examples/data/`:
+
+- **books.csv** -- 10,000 book records from Goodreads (id, title, author, isbn, ratings, etc.)
+- **seattle_neighborhoods/** -- Three Seattle ACS census datasets that share a Neighborhood Name column

package/examples/output/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "meadow-integration",
-    "version": "1.0.1",
+    "version": "1.0.4",
     "description": "Meadow Data Integration",
     "bin": {
         "mdwint": "source/cli/Meadow-Integration-CLI-Run.js"
@@ -16,7 +16,7 @@
     "author": "steven velozo <steven@velozo.com>",
     "license": "MIT",
     "devDependencies": {
-        "quackage": "^1.0.45"
+        "quackage": "^1.0.51"
     },
     "mocha": {
         "diff": true,
@@ -37,7 +37,10 @@
         ]
     },
     "dependencies": {
-        "fable-serviceproviderbase": "^3.0.15",
-        "pict-service-commandlineutility": "^1.0.16"
+        "fable": "^3.1.55",
+        "fable-serviceproviderbase": "^3.0.18",
+        "orator": "^6.0.0",
+        "orator-serviceserver-restify": "^2.0.5",
+        "pict-service-commandlineutility": "^1.0.18"
     }
 }

package/source/Meadow-Integration.js

@@ -1,6 +1,8 @@
 const libTabularCheck = require(`./services/tabular/Service-TabularCheck.js`);
+const libIntegrationServer = require(`./restserver/Meadow-Integration-Server.js`);
 
 module.exports = (
 	{
-		TabularCheck: libTabularCheck
+		TabularCheck: libTabularCheck,
+		IntegrationServer: libIntegrationServer
 	});

package/source/cli/Meadow-Integration-CLI-Program.js

@@ -30,7 +30,10 @@ let _PictCLIProgram = new libCLIProgram(
 		require('./commands/Meadow-Integration-Command-ComprehensionIntersect.js'),
 		require('./commands/Meadow-Integration-Command-ComprehensionArray.js'),
 
-		require('./commands/Meadow-Integration-Command-ComprehensionPush.js')
+		require('./commands/Meadow-Integration-Command-ComprehensionPush.js'),
+
+		// REST server
+		require('./commands/Meadow-Integration-Command-Serve.js')
 	]);
 
 _PictCLIProgram.instantiateServiceProvider('FilePersistence');