IDataContext
Namespace: Meshmakers.Octo.Sdk.Common.EtlDataPipeline
Path-only data context exposed to ETL pipeline nodes. All access to the underlying document is performed through string paths; no JSON object types appear in the API surface.
public interface IDataContext : IDisposable
Implements IDisposable
Remarks:
Implements IDisposable because root contexts may own a
whose unmanaged buffer is released only on IDisposable.Dispose(). Callers that
construct a root context (typically DataContextImpl) should wrap it in using.
Child / iteration contexts hold no owned document; their Dispose is a no-op.
Properties
Parent
Reference to the parent context, or null if this is the root context.
public abstract IDataContext Parent { get; }
Property Value
Methods
Exists(String)
Returns true if a value exists at the given path.
bool Exists(string path)
Parameters
path String
Returns
GetKind(String)
Returns the DataKind classification of the value at the given path.
DataKind GetKind(string path)
Parameters
path String
Returns
Length(String)
Returns the length of the array or string at the given path.
int Length(string path)
Parameters
path String
Returns
Keys(String)
Enumerates the property keys of the object at the given path.
IEnumerable<string> Keys(string path)
Parameters
path String
Returns
Get<T>(String)
Reads the value at the given path and deserializes it to T.
T Get<T>(string path)
Type Parameters
T
Parameters
path String
Returns
T
Remarks:
For Int32 and Int64 (and their nullable forms, arrays and DTO members)
a JSON number is coerced, not matched on its raw text: 5.0 reads as 5 and a
fractional value rounds to even (5.7 to 6, 4.5 to 4), matching what Newtonsoft's
ToObject<int> did. This is required because integral doubles are serialized with a
trailing .0 by design — see NewtonsoftParityInt32Converter (AB#5275).
IDataContext.GetValue(String, Boolean) is deliberately NOT affected and keeps reals as
Double.
GetArray<T>(String)
Reads the array at the given path and deserializes each element to T.
Serialization uses SystemTextJsonOptions.Default (the SDK default, carrying CK/Rt converters).
IEnumerable<T> GetArray<T>(string path)
Type Parameters
T
Parameters
path String
Returns
Remarks:
Four shapes a pipeline author may write into a node's …Path setting, and what each yields:
an array ($.ids → ["a","b"]): one entry per element;
a scalar ($.id → "a"): widened to a single-entry array, so a
node configured for many values also accepts one;
a multi-match path — wildcard, recursive descent or filter
($.Items[*].RtId, $..RtId, $.Items[?(@.Kind=='Doc')].RtId): one entry per match,
in document order (AB#5351);
an absent path, an explicit null, an object, or a multi-match
path with no match: null — not an empty sequence.
A null result therefore means "nothing usable at that path"; nodes turn it into their own error.
GetValue(String, Boolean)
Reads the value at path as its natural CLR scalar
(bool / long / double / DateTime / string / null), via the shared JsonScalar rules.
Object and array kinds return null — navigate those via Get<T>.
object GetValue(string path, bool parseDateStrings)
Parameters
path String
parseDateStrings Boolean
Returns
TryGet<T>(String, out T)
Reads path as T. Returns false when the path is
absent (distinguishing missing from a present default), true otherwise (including explicit null).
bool TryGet<T>(string path, out T value)
Type Parameters
T
Parameters
path String
value T
Returns
Set<T>(String, T)
Writes a value to the overlay at the given path using default semantics.
void Set<T>(string path, T value)
Type Parameters
T
Parameters
path String
value T
Set<T>(String, T, DocumentModes, ValueKinds, TargetValueWriteModes)
Writes a value to the overlay at the given path with explicit document/value/write semantics.
void Set<T>(string path, T value, DocumentModes documentMode, ValueKinds valueKind, TargetValueWriteModes writeMode)
Type Parameters
T
Parameters
path String
value T
documentMode DocumentModes
valueKind ValueKinds
writeMode TargetValueWriteModes
Clear(String)
Removes the value at the given path from the overlay.
void Clear(string path)
Parameters
path String
IterateArrayAsync(String, Func<IDataContext, Task>)
Iterates the array at the given path, invoking body for each element with a child context.
Task IterateArrayAsync(string path, Func<IDataContext, Task> body)
Parameters
path String
Returns
IterateArrayAsync(String, IReadOnlyList<ValueTuple<String, String>>, Func<IDataContext, Task>)
Iterates the array at path like IDataContext.IterateArrayAsync(String, IReadOnlyList<ValueTuple<String, String>>, Func<IDataContext, Task>),
but each child context exposes additional alias paths whose values are resolved once
from the parent up front. This lets the body of the loop read e.g. $.full.X
to access fields on the outer document while still iterating individual array items.
Task IterateArrayAsync(string path, IReadOnlyList<ValueTuple<string, string>> aliases, Func<IDataContext, Task> body)
Parameters
path String
JSONPath of the array to iterate.
aliases IReadOnlyList<ValueTuple<String, String>>
Alias entries: each pair maps a logical alias path (e.g. $.full) visible to the
child context to a source path (e.g. $) evaluated against this parent context
before iteration begins. Reads on the child match aliases by longest prefix.
body Func<IDataContext, Task>
Callback invoked per array element with a child context.
Returns
IterateObjectAsync(String, Func<String, IDataContext, Task>)
Iterates the object properties at the given path, invoking body for each (key, child context).
Task IterateObjectAsync(string path, Func<string, IDataContext, Task> body)
Parameters
path String
body Func<String, IDataContext, Task>
Returns
IterateMatchesAsync(String, Func<IDataContext, Task>)
Iterates each match of a JSONPath expression, invoking body with a child context.
Task IterateMatchesAsync(string jsonPath, Func<IDataContext, Task> body)
Parameters
jsonPath String
Returns
UpdateMatchesAsync(String, Func<IDataContext, Task>)
For each match of jsonPath, invokes body with a
sub-context rooted at that match. Mutations performed by the body are written back to
THIS context's overlay at the match's canonical path. Allocations are proportional to
what the body writes, not to the full document size.
Task UpdateMatchesAsync(string jsonPath, Func<IDataContext, Task> body)
Parameters
jsonPath String
Returns
Remarks:
The body uses Get/Set on the sub-context to read and modify the match in place via "$.<sub-property>" paths. Mutations are applied to this context's overlay after the body completes for each match.
Select(String)
Returns a detached sub-context rooted at path, or null if absent.
The returned context owns its backing document; dispose it when done. Writes to it do NOT
merge back into this context.
IDataContext Select(string path)
Parameters
path String
Returns
SelectMatches(String)
Returns a detached, read-oriented sub-context per match of jsonPath.
Writes to a returned context do NOT merge back (use IDataContext.UpdateMatchesAsync(String, Func<IDataContext, Task>) for that).
Replaces the former EnumerateMatches JsonNode escape hatch.
IEnumerable<IDataContext> SelectMatches(string jsonPath)
Parameters
jsonPath String
Returns
CopyTo(String, String)
Copies the value at sourcePath to targetPath.
void CopyTo(string sourcePath, string targetPath)
Parameters
sourcePath String
targetPath String
WriteJsonTo(String, Stream)
Writes the JSON value at the given path to the destination stream as UTF-8.
void WriteJsonTo(string path, Stream destination)
Parameters
path String
destination Stream
SetFromJson(String, ReadOnlyMemory<Byte>)
Sets the value at the given path from a UTF-8 JSON document.
void SetFromJson(string path, ReadOnlyMemory<byte> utf8Json)
Parameters
path String
utf8Json ReadOnlyMemory<Byte>