fms-odata-js 0.3.0

package/src/index.ts

@@ -0,0 +1,81 @@
+export { FMSOData } from './client.js'
+export { Batch, Changeset } from './batch.js'
+export type {
+  BatchHandle,
+  BatchOpResult,
+  BatchReadOp,
+  BatchResult,
+} from './batch.js'
+export {
+  buildContainerJsonBody,
+  ContainerRef,
+  FM_CONTAINER_SUPPORTED_MIME_TYPES,
+  sniffContainerMime,
+  toBase64,
+} from './containers.js'
+export type {
+  ContainerDownload,
+  ContainerJsonValue,
+  ContainerUploadInput,
+  FMContainerMimeType,
+} from './containers.js'
+export { EntityRef } from './entity.js'
+export type { EntityWriteOptions, EntityRefInfo } from './entity.js'
+export { FMSODataError, FMScriptError, isFMSODataError, isFMScriptError } from './errors.js'
+export type { ODataErrorBody } from './errors.js'
+export { basicAuth, fmidAuth } from './http.js'
+export type { FMAuthScheme, FMAuthToken, FMAuthTokenProvider } from './http.js'
+export { MetadataFetcher } from './metadata.js'
+export type {
+  EdmAction,
+  EdmEntitySet,
+  EdmEntityType,
+  EdmProperty,
+  MetadataOptions,
+  ODataMetadata,
+} from './metadata.js'
+export { Filter, Query, filterFactory } from './query.js'
+export type { FilterFactory, FilterInput, OrderDir, QueryResult } from './query.js'
+export type { AggregateFunction } from '@fms-odata/spec-ts'
+export { ScriptInvoker } from './scripts.js'
+export type { ScriptOptions, ScriptResult, ScriptScope, ScriptIdentifier } from './scripts.js'
+export type { FMSODataOptions, TokenProvider, RequestOptions } from './types.js'
+export type { ODataLiteral } from './url.js'
+
+// ---------------------------------------------------------------------------
+// Spec alignment: re-export version and feature-flag helpers from @fms-odata/spec-ts
+// ---------------------------------------------------------------------------
+
+export {
+  FM_VERSION_NAMES,
+  FM_VERSION_MATRIX,
+  ODATA_PROTOCOL_VERSION,
+  hasFeature,
+  hasQueryOption,
+  minVersionForFeature,
+  parseServerVersion,
+  parseVersionString,
+} from '@fms-odata/spec-ts'
+export type {
+  FMVersionMajor,
+  FMVersionStatus,
+  FMFeatureFlags,
+  FMQueryOptionFlags,
+  FMVersionInfo,
+  FMServerVersion,
+} from '@fms-odata/spec-ts'
+
+// ---------------------------------------------------------------------------
+// Deprecated aliases (kept for backward compatibility with fm-odata-js).
+// These re-export the renamed symbols under their old names and will be
+// removed in a future major version. New code should use the FMSOData* names.
+// ---------------------------------------------------------------------------
+
+/** @deprecated Use `FMSOData` instead. */
+export { FMSOData as FMOData } from './client.js'
+/** @deprecated Use `FMSODataError` instead. */
+export { FMSODataError as FMODataError } from './errors.js'
+/** @deprecated Use `isFMSODataError` instead. */
+export { isFMSODataError as isFMODataError } from './errors.js'
+/** @deprecated Use `FMSODataOptions` instead. */
+export type { FMSODataOptions as FMODataOptions } from './types.js'

package/src/metadata.ts

@@ -0,0 +1,354 @@
+/**
+ * $metadata (EDMX/CSDL) fetch and lightweight parser.
+ *
+ * FMS returns a subset of the full OData CSDL spec. This module parses just
+ * what FMS emits: EntityTypes, EntitySets, and Actions (FileMaker scripts).
+ * No inheritance, complex types, or enums are expected.
+ *
+ * The parser is intentionally dependency-free and uses simple regex-based
+ * extraction to stay within the bundle budget (~1 KB gzipped).
+ */
+
+import { FMSODataError } from './errors.js'
+import { executeRequest, type HttpClientContext } from './http.js'
+import type { RequestOptions } from './types.js'
+import { parseServerVersion, type FMServerVersion } from '@fms-odata/spec-ts'
+
+/** Property on an entity type (field in FileMaker). */
+export interface EdmProperty {
+  name: string
+  type: string
+  nullable: boolean
+  maxLength?: number
+}
+
+/** Entity type (FileMaker table occurrence). */
+export interface EdmEntityType {
+  name: string
+  keys: string[]
+  properties: EdmProperty[]
+  navigationProperties: { name: string; target: string; collection: boolean }[]
+}
+
+/** Entity set (exposed layout/table in OData). */
+export interface EdmEntitySet {
+  name: string
+  entityType: string
+}
+
+/** Action (FileMaker script exposed as OData Action). */
+export interface EdmAction {
+  name: string
+  boundTo?: string
+  parameters: { name: string; type: string }[]
+}
+
+/** Parsed OData metadata document. */
+export interface ODataMetadata {
+  namespace: string
+  entityTypes: EdmEntityType[]
+  entitySets: EdmEntitySet[]
+  actions: EdmAction[]
+  /** Product version string extracted from Org.OData.Core.V1.ProductVersion annotation (if present). */
+  productVersion?: string
+  /** Full parsed server version (major.minor.patch + raw), if detected from $metadata. */
+  serverVersion?: FMServerVersion
+  /** Original XML, for debugging and forward compatibility. */
+  raw: string
+}
+
+/** Options for metadata fetch. */
+export interface MetadataOptions extends RequestOptions {
+  /** Force refetch, bypassing the internal cache. */
+  refresh?: boolean
+}
+
+/** @internal — parse a boolean XML attribute value. */
+function parseBoolAttr(value: string | undefined, defaultValue: boolean): boolean {
+  if (value === undefined) return defaultValue
+  return value === 'true'
+}
+
+/** @internal — extract the value of an XML attribute by name from a tag string. */
+function getAttr(text: string, name: string): string | undefined {
+  const re = new RegExp(`${name}="([^"]*)"`, 'i')
+  const m = text.match(re)
+  return m?.[1]
+}
+
+/** @internal — extract all attributes as a record from a tag open. */
+function getAttrs(text: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  const re = /(\w+)="([^"]*)"/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(text)) !== null) {
+    // m[1] and m[2] are always defined when the regex matches
+    out[m[1]!] = m[2]!
+  }
+  return out
+}
+
+/** @internal — find all top-level elements with the given tag name, handling namespace prefixes. */
+function findElements(xml: string, tagName: string): string[] {
+  const results: string[] = []
+  // Match both <Tag ...> and <prefix:Tag ...> (self-closing or with content)
+  // [\\w]+ matches word characters (properly escaped for RegExp string)
+  const openRe = new RegExp(`<([\\w]+:)?${tagName}\\b[^>]*>`, 'gi')
+  let m: RegExpExecArray | null
+  while ((m = openRe.exec(xml)) !== null) {
+    const openTag = m[0]
+    // Self-closing tag: <... />
+    if (/\/>\s*$/.test(openTag)) {
+      results.push(openTag)
+      continue
+    }
+    // Find matching close tag; naive but adequate for FMS CSDL which isn't deeply nested.
+    const startIdx = m.index
+    const closeRe = new RegExp(`</([\\w]+:)?${tagName}>`, 'gi')
+    closeRe.lastIndex = openRe.lastIndex
+    const closeM = closeRe.exec(xml)
+    if (closeM) {
+      results.push(xml.slice(startIdx, closeM.index + closeM[0].length))
+    }
+  }
+  return results
+}
+
+/** @internal — extract inner XML between the outermost matching open/close tags (handles namespace prefixes). */
+function elementContent(xml: string, tagName: string): string | undefined {
+  // Match tag with optional namespace prefix: <tag>, <prefix:tag>
+  const openRe = new RegExp(`<(?:[\\w]+:)?${tagName}\\b[^>]*>`, 'i')
+  const openM = openRe.exec(xml)
+  if (!openM) return undefined
+  const startIdx = openM.index + openM[0].length
+  // Match closing tag with optional namespace prefix
+  const closeRe = new RegExp(`</(?:[\\w]+:)?${tagName}>`, 'i')
+  closeRe.lastIndex = startIdx
+  const closeM = closeRe.exec(xml)
+  if (!closeM) return undefined
+  return xml.slice(startIdx, closeM.index)
+}
+
+/** @internal — parse <Property Name="..." Type="..." Nullable="..." [MaxLength="..."] /> */
+function parseProperty(xml: string): EdmProperty {
+  const attrs = getAttrs(xml)
+  const nullable = parseBoolAttr(attrs.Nullable, true)
+  const out: EdmProperty = {
+    name: attrs.Name ?? '',
+    type: attrs.Type ?? '',
+    nullable,
+  }
+  if (attrs.MaxLength !== undefined) {
+    const n = parseInt(attrs.MaxLength, 10)
+    if (!Number.isNaN(n)) out.maxLength = n
+  }
+  return out
+}
+
+/** @internal — parse <NavigationProperty Name="..." Type="..." /> */
+function parseNavigationProperty(xml: string): { name: string; target: string; collection: boolean } {
+  const attrs = getAttrs(xml)
+  const type = attrs.Type ?? ''
+  const collection = type.startsWith('Collection(')
+  const target = collection ? type.slice(11, -1) : type
+  return {
+    name: attrs.Name ?? '',
+    target,
+    collection,
+  }
+}
+
+/** @internal — parse <Key><PropertyRef Name="..." /></Key> */
+function parseKey(xml: string): string[] {
+  const keys: string[] = []
+  const refs = findElements(xml, 'PropertyRef')
+  for (const ref of refs) {
+    const name = getAttr(ref, 'Name')
+    if (name) keys.push(name)
+  }
+  return keys
+}
+
+/** @internal — parse <EntityType Name="...">...</EntityType> */
+function parseEntityType(xml: string): EdmEntityType {
+  const name = getAttr(xml, 'Name') ?? ''
+  const keys: string[] = []
+  const properties: EdmProperty[] = []
+  const navigationProperties: EdmEntityType['navigationProperties'] = []
+
+  const inner = elementContent(xml, 'EntityType') ?? xml
+
+  // Key
+  const keyEl = findElements(inner, 'Key')[0]
+  if (keyEl) {
+    keys.push(...parseKey(keyEl))
+  }
+
+  // Properties
+  for (const prop of findElements(inner, 'Property')) {
+    properties.push(parseProperty(prop))
+  }
+
+  // Navigation Properties
+  for (const nav of findElements(inner, 'NavigationProperty')) {
+    navigationProperties.push(parseNavigationProperty(nav))
+  }
+
+  return { name, keys, properties, navigationProperties }
+}
+
+/** @internal — parse <EntitySet Name="..." EntityType="..." /> */
+function parseEntitySet(xml: string): EdmEntitySet {
+  const attrs = getAttrs(xml)
+  return {
+    name: attrs.Name ?? '',
+    entityType: attrs.EntityType ?? '',
+  }
+}
+
+/**
+ * @internal — extract the FileMaker Server version from the metadata XML using
+ * the multi-strategy parser from @fms-odata/spec-ts.
+ *
+ * Detection strategies (in priority order):
+ * 1a. Org.OData.Core.V1.ProductVersion annotation with String attribute
+ * 1b. Same as 1a but with reversed attribute order
+ * 1c. ServerVersion annotation (FM 26+, e.g. "OData Engine 26.0.1")
+ * 1d. Same as 1c but with reversed attribute order
+ * 2.  Generic fallback: any annotation term containing "Version" with major >= 17
+ *
+ * Returns the full FMServerVersion object, or undefined if not found.
+ */
+function extractServerVersion(xml: string): FMServerVersion | undefined {
+  return parseServerVersion(xml) ?? undefined
+}
+
+/** @internal — parse <Action Name="...">[...parameters...]</Action> */
+function parseAction(xml: string): EdmAction {
+  const name = getAttr(xml, 'Name') ?? ''
+  const attrs = getAttrs(xml)
+  const boundTo = attrs['IsBound'] === 'true' ? attrs['EntityType'] : undefined
+
+  const parameters: EdmAction['parameters'] = []
+  const inner = elementContent(xml, 'Action') ?? xml
+  for (const p of findElements(inner, 'Parameter')) {
+    const pAttrs = getAttrs(p)
+    parameters.push({
+      name: pAttrs.Name ?? '',
+      type: pAttrs.Type ?? '',
+    })
+  }
+
+  return boundTo !== undefined ? { name, boundTo, parameters } : { name, parameters }
+}
+
+/**
+ * @internal — parse raw CSDL XML into ODataMetadata.
+ * Throws FMSODataError for malformed XML.
+ */
+export function parseMetadata(xml: string): ODataMetadata {
+  try {
+    // Extract Edmx/DataServices/Schema
+    const dataServices = elementContent(xml, 'DataServices')
+    if (!dataServices) {
+      throw new Error('Missing <edmx:DataServices> in metadata')
+    }
+
+    const schema = findElements(dataServices, 'Schema')[0]
+    if (!schema) {
+      throw new Error('Missing <Schema> in metadata')
+    }
+
+    const namespace = getAttr(schema, 'Namespace') ?? ''
+    const schemaInner = elementContent(schema, 'Schema') ?? schema
+
+    // Parse EntityTypes
+    const entityTypes: EdmEntityType[] = []
+    for (const et of findElements(schemaInner, 'EntityType')) {
+      entityTypes.push(parseEntityType(et))
+    }
+
+    // Parse EntitySets (inside EntityContainer)
+    const entitySets: EdmEntitySet[] = []
+    const container = findElements(schemaInner, 'EntityContainer')[0]
+    if (container) {
+      const containerInner = elementContent(container, 'EntityContainer') ?? container
+      for (const es of findElements(containerInner, 'EntitySet')) {
+        entitySets.push(parseEntitySet(es))
+      }
+    }
+
+    // Parse Actions (FileMaker scripts surface here)
+    const actions: EdmAction[] = []
+    for (const a of findElements(schemaInner, 'Action')) {
+      actions.push(parseAction(a))
+    }
+
+    // Extract server version using the multi-strategy parser from @fms-odata/spec-ts.
+    // Handles ProductVersion, ServerVersion (FM 26+), reversed attribute order,
+    // and a generic fallback for non-standard annotation terms.
+    const serverVersion = extractServerVersion(xml)
+
+    const result: ODataMetadata = {
+      namespace,
+      entityTypes,
+      entitySets,
+      actions,
+      raw: xml,
+    }
+    if (serverVersion) {
+      result.serverVersion = serverVersion
+      // Keep productVersion for backward compatibility (raw string only)
+      result.productVersion = serverVersion.raw
+    }
+    return result
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    throw new FMSODataError(`Failed to parse $metadata: ${message}`, {
+      status: 0,
+      odataError: xml.slice(0, 500),
+    })
+  }
+}
+
+/**
+ * @internal — fetch raw $metadata XML.
+ */
+export async function fetchMetadataXml(
+  ctx: HttpClientContext,
+  baseUrl: string,
+  opts: RequestOptions = {},
+): Promise<string> {
+  const res = await executeRequest(ctx, `${baseUrl}/$metadata`, {
+    method: 'GET',
+    accept: 'xml',
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  })
+  return res.text()
+}
+
+/**
+ * Metadata fetcher bound to a client. Caches by default; pass `refresh: true` to bypass.
+ * @internal — exported for testing; use via `FMSOData#metadata()`.
+ */
+export class MetadataFetcher {
+  private _cache: Promise<ODataMetadata> | undefined
+
+  constructor(
+    private _ctx: HttpClientContext,
+    private _baseUrl: string,
+  ) {}
+
+  async fetchXml(opts: RequestOptions = {}): Promise<string> {
+    return fetchMetadataXml(this._ctx, this._baseUrl, opts)
+  }
+
+  async fetch(opts: MetadataOptions = {}): Promise<ODataMetadata> {
+    if (!opts.refresh && this._cache) {
+      return this._cache
+    }
+    const promise = this.fetchXml(opts).then(parseMetadata)
+    this._cache = promise
+    return promise
+  }
+}