Basic Read with Load Meta Example

This example demonstrates how to read a CSV file using metadata loaded from an XML string.

What it does

1. Defines metadata in XML format (FieldedText standard format) with 2 heading lines
2. Loads the metadata using XmlMetaSerializer.deserialize()
3. Uses FtReader to parse CSV data
4. Gets field ordinals for efficient field access
5. Reads and displays each record using ordinal-based field access

Running the example

npx tsx examples/basic-read-load-meta/index.ts
Copy

Expected output

Loading metadata from XML...
Loaded metadata with 7 fields

Reading CSV data:
================

1: Rover, 4.5 years, Brown, received 2/12/2004, $80, walks: true, Dog
2: Charlie, null years, Gold, received 4/5/2007, $12.3, walks: false, Fish
3: Molly, 2 years, Black, received 12/25/2006, $25, walks: false, Cat
4: Gilly, null years, White, received 4/10/2007, $10, walks: false, Guinea Pig

Total records read: 4
Copy

Key concepts

• XML Metadata: Standard format for defining fielded text structure
• XmlMetaSerializer: Serializes and deserializes metadata to/from XML
• Field Ordinals: Using getFieldIndexByName() for efficient field access (faster than getFieldByName())
• Metadata Reusability: XML metadata can be saved to files and reused
• Standards Compliance: XML format follows FieldedText Standard v0.9
• FtReader: High-level reader with using statement support

Comparison with Build Meta

The basic-read-build-meta example builds metadata programmatically in code and uses getFieldByName() for field access. This example loads metadata from XML and uses field ordinals, which is useful for:

• Sharing metadata across different programs
• Version controlling metadata separately from code
• Interoperability with C# FieldedText library
• Complex metadata that's easier to manage in XML
• Better performance when accessing fields repeatedly (ordinal-based access is faster)

Code

// Basic Read with Load Meta Example
// Demonstrates reading a CSV file by loading metadata from XML

import { FtReader, FtXmlMetaSerialization } from "@pbkware/fielded-text-web";

// Sample CSV data - matches C# BasicExample.csv
const csvData = `"Pet Name","Age","Color","Date Received","Price","Needs Walking","Type"
"","(Years)","","","(Dollars)","",""
Rover,4.5,Brown,12 Feb 2004,80,True,Dog
Charlie,,Gold,5 Apr 2007,12.3,False,Fish
Molly,2,Black,25 Dec 2006,25,False,Cat
Gilly,,White,10 Apr 2007,10,False,Guinea Pig`;

// Meta XML - matches C# BasicExampleMeta.ftm
const metaXml = `<?xml version="1.0" encoding="utf-8"?>
<FieldedText HeadingLineCount="2">
  <Field Name="PetName" />
  <Field DataType="Float" Name="Age" />
  <Field Name="Color" />
  <Field DataType="DateTime" Name="DateReceived" Format="d MMM yyyy" />
  <Field DataType="Decimal" Name="Price" />
  <Field DataType="Boolean" Name="NeedsWalking" />
  <Field Name="Type" />
</FieldedText>`;

// Define field names
const petNameFieldName = "PetName";
const ageFieldName = "Age";
const colorFieldName = "Color";
const dateReceivedFieldName = "DateReceived";
const priceFieldName = "Price";
const needsWalkingFieldName = "NeedsWalking";
const typeFieldName = "Type";

// Load metadata from XML
console.log("Loading metadata from XML...");
const meta = FtXmlMetaSerialization.deserialize(metaXml);

console.log(`Loaded metadata with ${meta.fieldList.count} fields\n`);

// Create reader and read CSV
const reader = new FtReader(meta, csvData);

console.log("Reading CSV data:");
console.log("================\n");

// Get field ordinals for faster access (compared to calling getFieldByName() for each record)
const petNameFieldOrdinal = reader.getFieldIndexByName(petNameFieldName)!;
const ageFieldOrdinal = reader.getFieldIndexByName(ageFieldName)!;
const colorFieldOrdinal = reader.getFieldIndexByName(colorFieldName)!;
const dateReceivedFieldOrdinal = reader.getFieldIndexByName(
  dateReceivedFieldName,
)!;
const priceFieldOrdinal = reader.getFieldIndexByName(priceFieldName)!;
const needsWalkingFieldOrdinal = reader.getFieldIndexByName(
  needsWalkingFieldName,
)!;
const typeFieldOrdinal = reader.getFieldIndexByName(typeFieldName)!;

let recordNumber = 0;
while (reader.read()) {
  recordNumber++;

  const petName = reader.fieldList.get(petNameFieldOrdinal).asString;
  const age = reader.fieldList.get(ageFieldOrdinal).asNullableFloat; // Use asNullableFloat to handle null values
  const color = reader.fieldList.get(colorFieldOrdinal).asString;
  const dateReceived = reader.fieldList.get(
    dateReceivedFieldOrdinal,
  ).asDateTime;
  const price = reader.fieldList.get(priceFieldOrdinal).asDecimal;
  const needsWalking = reader.fieldList.get(needsWalkingFieldOrdinal).asBoolean;
  const type = reader.fieldList.get(typeFieldOrdinal).asString;

  console.log(
    `${recordNumber}: ${petName}, ${age} years, ${color}, received ${dateReceived.toLocaleDateString()}, $${price}, walks: ${needsWalking}, ${type}`,
  );
}

console.log(`\nTotal records read: ${recordNumber}`);
Copy