OData V4 Literal Converter

Common errors

• Cannot read properties of undefined (reading 'convert') or similar TypeError

  cause The `Literal` object was not correctly imported or accessed from the package's module export.
  fix Ensure you are using `import { Literal } from 'odata-v4-literal';` for ESM or `const { Literal } = require('odata-v4-literal');` for CommonJS to correctly destructure the named export.

• Error: Unrecognized literal format or Malformed OData literal

  cause The input string does not conform to the expected OData V4 literal format for the specified EDM type.
  fix Review the OData V4 specification for the correct literal format for the EDM type you are trying to convert. Pay close attention to string delimiters (single quotes), date/time formats (ISO 8601), and special character escaping (e.g., doubling single quotes within a string literal).

Warnings

• breaking The package version is 0.1.1 and has not been updated in over nine years. There are no guarantees of semantic versioning (SemVer) compliance. Future (hypothetical) updates or even minor bug fixes could introduce breaking changes without a major version increment. However, given its abandoned status, no future updates are expected.
  Fix: Consider alternatives for new projects or thoroughly vet the package's stability and compatibility for existing applications. Pin the exact version used to mitigate unexpected behavior if it were to be updated.
• gotcha OData V4 string literals require single quotes to be escaped by doubling them (e.g., 'O''Neill' for 'O'Neill'). Incorrectly escaping strings will lead to parsing errors or incorrect values. This is a common pitfall in OData filter expressions.
  Fix: Always escape single quotes within OData string literals by doubling them. For example, use `'It''s a test'` instead of `'It's a test'`.
• gotcha This package is effectively abandoned, with its last publish occurring over nine years ago. This means there will be no future updates, bug fixes, security patches, or compatibility improvements for newer Node.js versions, TypeScript versions, or OData specification changes. Use with caution in new projects, as it may become incompatible or insecure over time.
  Fix: For new projects, seek actively maintained OData V4 parsing libraries. For existing projects, thoroughly test its behavior in your current environment and be prepared for potential incompatibilities with future platform updates.

Install

• npm install odata-v4-literal npm
• yarn add odata-v4-literal yarn
• pnpm add odata-v4-literal pnpm

Imports

• Literal
  wrong:

  import Literal from 'odata-v4-literal';

  correct:

  import { Literal } from 'odata-v4-literal';

  The package exports `Literal` as a named export from its CommonJS module. While this ESM import generally works with bundlers and Node.js resolution, direct default import is incorrect.
• Literal (CommonJS)
  wrong:

  const Literal = require('odata-v4-literal');

  correct:

  const { Literal } = require('odata-v4-literal');

  The `require` call returns an object containing the `Literal` utility, not `Literal` directly. Destructuring is the correct approach for CommonJS environments.

Quickstart

This quickstart demonstrates how to use `odata-v4-literal` to convert various OData V4 literal string representations into their native JavaScript types, including strings with escaped characters, numbers, booleans, GUIDs, and date/time types. It also shows basic error handling for malformed input.

import { Literal } from 'odata-v4-literal';

// Demonstrate conversion of various OData V4 literal types
console.log('--- OData V4 Literal Conversions ---');

// Edm.String (note the escaping for O'Neill)
const string1 = Literal.convert("Edm.String", "'Hello O''Neill'");
console.log(`'Hello O''Neill' (Edm.String) -> ${JSON.stringify(string1)} (Type: ${typeof string1})`);

// Another simple Edm.String
const string2 = Literal.convert("Edm.String", "'Another String'");
console.log(`'Another String' (Edm.String) -> ${JSON.stringify(string2)} (Type: ${typeof string2})`);

// Edm.Int32
const int32 = Literal.convert("Edm.Int32", "123");
console.log(`123 (Edm.Int32) -> ${JSON.stringify(int32)} (Type: ${typeof int32})`);

// Edm.Decimal / Edm.Double
const decimal = Literal.convert("Edm.Decimal", "123.45");
console.log(`123.45 (Edm.Decimal) -> ${JSON.stringify(decimal)} (Type: ${typeof decimal})`);

// Edm.Boolean
const booleanTrue = Literal.convert("Edm.Boolean", "true");
console.log(`true (Edm.Boolean) -> ${JSON.stringify(booleanTrue)} (Type: ${typeof booleanTrue})`);

const booleanFalse = Literal.convert("Edm.Boolean", "false");
console.log(`false (Edm.Boolean) -> ${JSON.stringify(booleanFalse)} (Type: ${typeof booleanFalse})`);

// Edm.Guid
const guid = Literal.convert("Edm.Guid", "80336209-66cb-4034-8b63-952467d344ff");
console.log(`80336209-66cb-4034-8b63-952467d344ff (Edm.Guid) -> ${JSON.stringify(guid)} (Type: ${typeof guid})`);

// Edm.DateTimeOffset (ISO 8601 format)
const dateTimeOffset = Literal.convert("Edm.DateTimeOffset", "2023-01-15T10:30:00Z");
console.log(`2023-01-15T10:30:00Z (Edm.DateTimeOffset) -> ${JSON.stringify(dateTimeOffset)} (Type: ${typeof dateTimeOffset})`);

// Edm.Date
const date = Literal.convert("Edm.Date", "2023-01-15");
console.log(`2023-01-15 (Edm.Date) -> ${JSON.stringify(date)} (Type: ${typeof date})`);

// Example of a potentially malformed literal (unquoted string for Edm.String)
try {
    // This will likely throw an error or return null/undefined depending on implementation
    const malformed = Literal.convert("Edm.String", "Unquoted String");
    console.log(`'Unquoted String' (malformed Edm.String) -> ${JSON.stringify(malformed)}`);
} catch (e: any) {
    console.error(`Error converting malformed string literal: ${e.message}`);
}