Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/guides/modeling/conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ for the behaviors that are policy, not mapping.
| Element names (Cosmos DB) | camelCase (System.Text.Json web defaults) |
| Columns vs navigations (relational) | scalars (and scalar collections, for stores with array columns) map to columns; entity references and entity collections are navigations |
| Foreign keys (relational `Include`) | reference `Order` → `OrderId` on this entity; collection of `Item` → `{Entity}Id` on the element (`Reference(…)`/`Collection(…)` override) |
| A stored null, on read | `null` in the member, or its type's default when the member cannot hold null, on every engine and every read (by key, listings, raw SQL), whatever the member's initializer: `int? Quota { get; set; } = 10` reads a NULL row as `null`, never 10. An initializer is what a new entity starts with, not what a read fills in |

## `DataConventions` — the write-policy object

Expand Down
10 changes: 8 additions & 2 deletions src/eQuantic.Core.Data.Cassandra/CassandraMapper.cs
Original file line number Diff line number Diff line change
Expand Up @@ -223,12 +223,18 @@ public static TEntity Materialize<TEntity>(CassandraEntityConfiguration configur
// lower-cased name; the driver's by-name lookup is case-sensitive, so read with that name (the
// property, matched case-insensitively, still carries the original casing).
var name = column.Name.ToLowerInvariant();
if (property is null || !property.CanWrite || row.IsNull(name))
if (property is null || !property.CanWrite)
{
continue;
}

property.SetValue(entity, Value(row, column, property.PropertyType, name));
// A null is written too: skipped, a member the entity initializes would read its initializer, not what the
// row holds. A member that cannot hold null reads its type's default.
property.SetValue(entity, row.IsNull(name)
? property.PropertyType.IsValueType && Nullable.GetUnderlyingType(property.PropertyType) is null
? Activator.CreateInstance(property.PropertyType)
: null
: Value(row, column, property.PropertyType, name));
}

return entity;
Expand Down
32 changes: 21 additions & 11 deletions src/eQuantic.Core.Data.Relational/RelationalMaterializer.cs
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,12 @@ public static object Materialize(Type entityType, DbDataReader reader, IReadOnly
var entity = accessor?.Create() ?? Activator.CreateInstance(entityType)!;
for (var ordinal = 0; ordinal < selected.Count; ordinal++)
{
if (reader.IsDBNull(ordinal))
{
continue;
}

// A NULL is written too: skipped, a member the entity initializes would read its initializer, not what
// the row holds.
var column = selected[ordinal];
var value = Cell(column, reader.GetValue(ordinal), column.Property.PropertyType);
var value = reader.IsDBNull(ordinal)
? NullFor(column.Property.PropertyType)
: Cell(column, reader.GetValue(ordinal), column.Property.PropertyType);
if (accessor is not null)
{
accessor.Set(entity, column.Property.Name, value);
Expand All @@ -56,15 +55,19 @@ public static TEntity MaterializeByName<TEntity>(DbDataReader reader, Relational
var entity = Activator.CreateInstance<TEntity>()!;
for (var ordinal = 0; ordinal < reader.FieldCount; ordinal++)
{
if (reader.IsDBNull(ordinal))
var name = reader.GetName(ordinal);
var column = configuration.Columns.FirstOrDefault(candidate =>
string.Equals(candidate.Name, name, StringComparison.OrdinalIgnoreCase));
if (column is null)
{
continue;
}

var name = reader.GetName(ordinal);
var column = configuration.Columns.FirstOrDefault(candidate =>
string.Equals(candidate.Name, name, StringComparison.OrdinalIgnoreCase));
if (column is not null)
if (reader.IsDBNull(ordinal))
{
column.Property.SetValue(entity, NullFor(column.Property.PropertyType));
}
else
{
Assign(entity, column, reader.GetValue(ordinal));
}
Expand All @@ -73,6 +76,13 @@ public static TEntity MaterializeByName<TEntity>(DbDataReader reader, Relational
return entity;
}

/// <summary>
/// What a NULL cell reads as in a member of <paramref name="memberType" />: <c>null</c>, or the type's default
/// where it cannot hold one, as a projection reads it. Never the value the member was initialized with.
/// </summary>
internal static object? NullFor(Type memberType) =>
memberType.IsValueType && Nullable.GetUnderlyingType(memberType) is null ? Activator.CreateInstance(memberType) : null;

/// <summary>Converts a reader value into a target CLR type (nullable unwrap, enum and numeric coercions).</summary>
internal static object? ChangeValue(object? value, Type target)
{
Expand Down
10 changes: 4 additions & 6 deletions src/eQuantic.Core.Data.Relational/RelationalRowBinder.cs
Original file line number Diff line number Diff line change
Expand Up @@ -78,12 +78,10 @@ public TResult Bind(DbDataReader reader)

foreach (var (ordinal, property) in _bindings)
{
if (reader.IsDBNull(ordinal))
{
continue;
}

var value = RelationalMaterializer.ChangeValue(reader.GetValue(ordinal), property.PropertyType);
// A NULL is written too, so a member the result type initializes reads what the row holds.
var value = reader.IsDBNull(ordinal)
? RelationalMaterializer.NullFor(property.PropertyType)
: RelationalMaterializer.ChangeValue(reader.GetValue(ordinal), property.PropertyType);
if (_accessor is not null)
{
_accessor.Set(result!, property.Name, value);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,27 @@ public sealed class Page : IEntity<Guid>
public void SetKey(Guid key) => Id = key;
}

/// <summary>
/// A row whose nullable members start with a value, as a generated model carries a column's default: a stored null
/// must read as null, never as the value the member starts with.
/// </summary>
public sealed class Preset : IEntity<Guid>
{
public Guid Id { get; set; } = Guid.NewGuid();

public string? Note { get; set; } = "initial";

public int? Quota { get; set; } = 10;

public bool? Enabled { get; set; } = true;

public DateTime? Since { get; set; } = new(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc);

public Guid GetKey() => Id;

public void SetKey(Guid key) => Id = key;
}

/// <summary>A row whose number and stamp the store assigns.</summary>
public sealed class Voucher : IEntity<Guid>
{
Expand Down Expand Up @@ -117,6 +138,7 @@ private static void Model(CassandraModelBuilder builder) => builder
.Entity<QueuedJob>(entity => entity.Table("queued_jobs").PartitionKey(x => x.Id))
.Entity<ItemType>(entity => entity.Table("item_types").PartitionKey(x => x.Id))
.Entity<Page>(entity => entity.Table("pages").PartitionKey(x => x.Id))
.Entity<Preset>(entity => entity.Table("presets").PartitionKey(x => x.Id))
.Entity<Voucher>(entity => entity
.Table("vouchers")
.PartitionKey(x => x.Id)
Expand All @@ -135,6 +157,7 @@ await _db.Resolve<IMigrationExecutor>().ApplyAsync(new MigrationBuilder()
.For<QueuedJob>(table => table.EnsureCollection())
.For<ItemType>(table => table.EnsureCollection())
.For<Page>(table => table.EnsureCollection())
.For<Preset>(table => table.EnsureCollection())
.For<Voucher>(table => table.EnsureCollection())
.For<Tally>(table => table.EnsureCollection())
.Operations);
Expand Down Expand Up @@ -546,4 +569,28 @@ public async Task A_member_scoped_modify_leaves_the_other_members()
Assert.That(stored.Locked, Is.True);
Assert.That(stored.Body, Is.EqualTo("text"));
}

[Test]
public async Task A_stored_null_reads_as_null_in_a_member_that_starts_with_a_value()
{
var preset = new Preset { Note = null, Quota = null, Enabled = null, Since = null };
var kept = new Preset();
using (var seed = NewScope())
{
await Repo<Preset, Guid>(seed).AddAsync(preset);
await Repo<Preset, Guid>(seed).AddAsync(kept);
await Commit(seed);
}

using var check = NewScope();
var stored = (await Repo<Preset, Guid>(check).GetAsync(preset.Id))!;
Assert.That(new object?[] { stored.Note, stored.Quota, stored.Enabled, stored.Since }, Is.All.Null);

var listed = (await Repo<Preset, Guid>(check).GetAllAsync()).Single(row => row.Id == preset.Id);
Assert.That(new object?[] { listed.Note, listed.Quota, listed.Enabled, listed.Since }, Is.All.Null);

var other = (await Repo<Preset, Guid>(check).GetAsync(kept.Id))!;
Assert.That((other.Note, other.Quota, other.Enabled, other.Since),
Is.EqualTo(("initial", (int?)10, (bool?)true, (DateTime?)new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc))));
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,7 @@ private static void RegisterEntities(CosmosModelBuilder model) => ReadShapesMode
.Entity<Job>(entity => entity.Container(ContainerName).PartitionKey(x => x.Category))
.Entity<ItemType>(entity => entity.Container(ContainerName).PartitionKey(x => x.Category))
.Entity<Page>(entity => entity.Container(ContainerName).PartitionKey(x => x.Category))
.Entity<Preset>(entity => entity.Container(ContainerName).PartitionKey(x => x.Category))
.Entity<WideRecord>(entity => entity.Container(ContainerName).PartitionKey(x => x.Category).ConcurrencyToken(x => x.ETag))
.Entity<RelItem>(entity => entity.Container("rel_items").PartitionKey(x => x.Category))
.Entity<RelMention>(entity => entity.Container("rel_mentions").PartitionKey(x => x.Category))
Expand Down
47 changes: 47 additions & 0 deletions tests/eQuantic.Core.Data.CosmosDb.Tests/CosmosWriteOutcomeTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,29 @@ public sealed class Page : IEntity<string>
public void SetKey(string key) => Id = key;
}

/// <summary>
/// A document whose nullable members start with a value, as a generated model carries a column's default: a stored
/// null must read as null, never as the value the member starts with.
/// </summary>
public sealed class Preset : IEntity<string>
{
public string Id { get; set; } = Guid.NewGuid().ToString("N");

public string Category { get; set; } = "";

public string? Note { get; set; } = "initial";

public int? Quota { get; set; } = 10;

public bool? Enabled { get; set; } = true;

public DateTime? Since { get; set; } = new(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc);

public string GetKey() => Id;

public void SetKey(string key) => Id = key;
}

/// <summary>
/// A record with more members than Cosmos DB patches in one operation: an update of all twelve, with the status, goes
/// as several patches of the item in one transactional batch. Its <c>_etag</c> is its concurrency token.
Expand Down Expand Up @@ -531,6 +554,30 @@ public async Task A_member_scoped_modify_leaves_the_other_members()
Assert.That(stored.Locked, Is.True);
Assert.That(stored.Body, Is.EqualTo("text"));
}

[Test]
public async Task A_stored_null_reads_as_null_in_a_member_that_starts_with_a_value()
{
var preset = new Preset { Category = Partition, Note = null, Quota = null, Enabled = null, Since = null };
var kept = new Preset { Category = Partition };
using (var seed = NewScope())
{
await RepoOf<Preset>(seed).AddAsync(preset);
await RepoOf<Preset>(seed).AddAsync(kept);
await Commit(seed);
}

using var check = NewScope();
var stored = (await RepoOf<Preset>(check).GetAsync(preset.Id))!;
Assert.That(new object?[] { stored.Note, stored.Quota, stored.Enabled, stored.Since }, Is.All.Null);

var listed = (await RepoOf<Preset>(check).GetFilteredAsync(row => row.Id == preset.Id)).Single();
Assert.That(new object?[] { listed.Note, listed.Quota, listed.Enabled, listed.Since }, Is.All.Null);

var other = (await RepoOf<Preset>(check).GetAsync(kept.Id))!;
Assert.That((other.Note, other.Quota, other.Enabled, other.Since),
Is.EqualTo(("initial", (int?)10, (bool?)true, (DateTime?)new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc))));
}
// ---------------------------------------------------------------- more paths than one patch takes

private static readonly System.Linq.Expressions.Expression<Func<WideRecord, object?>> TwelveMembers = x => new
Expand Down
44 changes: 44 additions & 0 deletions tests/eQuantic.Core.Data.MongoDb.Tests/MongoWriteOutcomeTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,26 @@ public sealed class Page : IEntity<string>
public void SetKey(string key) => Id = key;
}

/// <summary>
/// A document whose nullable members start with a value, as a generated model carries a column's default: a stored
/// null must read as null, never as the value the member starts with.
/// </summary>
public sealed class Preset : IEntity<string>
{
public string Id { get; set; } = Guid.NewGuid().ToString("N");
public string? Note { get; set; } = "initial";

public int? Quota { get; set; } = 10;

public bool? Enabled { get; set; } = true;

public DateTime? Since { get; set; } = new(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc);

public string GetKey() => Id;

public void SetKey(string key) => Id = key;
}

/// <summary>An account whose e-mail is unique under the index <c>ix_users_email</c>.</summary>
public sealed class UserAccount : IEntity<string>
{
Expand Down Expand Up @@ -682,4 +702,28 @@ public async Task A_member_scoped_modify_leaves_the_other_members()
Assert.That(stored.Locked, Is.True);
Assert.That(stored.Body, Is.EqualTo("text"));
}

[Test]
public async Task A_stored_null_reads_as_null_in_a_member_that_starts_with_a_value()
{
var preset = new Preset { Note = null, Quota = null, Enabled = null, Since = null };
var kept = new Preset();
using (var seed = NewScope())
{
await Repo<Preset>(seed).AddAsync(preset);
await Repo<Preset>(seed).AddAsync(kept);
await Commit(seed);
}

using var check = NewScope();
var stored = (await Repo<Preset>(check).GetAsync(preset.Id))!;
Assert.That(new object?[] { stored.Note, stored.Quota, stored.Enabled, stored.Since }, Is.All.Null);

var listed = (await Repo<Preset>(check).GetAllAsync()).Single(row => row.Id == preset.Id);
Assert.That(new object?[] { listed.Note, listed.Quota, listed.Enabled, listed.Since }, Is.All.Null);

var other = (await Repo<Preset>(check).GetAsync(kept.Id))!;
Assert.That((other.Note, other.Quota, other.Enabled, other.Since),
Is.EqualTo(("initial", (int?)10, (bool?)true, (DateTime?)new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc))));
}
}
3 changes: 3 additions & 0 deletions tests/eQuantic.Core.Data.MySql.Tests/MariaDbTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,9 @@ public Task A_staged_insert_of_a_taken_key_fails_the_commit_atomically() =>
[Test]
public Task A_member_scoped_modify_leaves_the_other_members() => WriteOutcomeScenarios.PartialModifyKeepsOtherMembers(NewScope);

[Test]
public Task A_stored_null_reads_as_null_in_a_member_that_starts_with_a_value() => WriteOutcomeScenarios.StoredNullReadsAsNull(NewScope);

[Test]
public Task A_bulk_load_of_a_taken_key_fails() => WriteOutcomeScenarios.BulkInsertOfTakenKeyFails(NewScope);

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,9 @@ public Task A_staged_insert_of_a_taken_key_fails_the_commit_atomically() =>
[Test]
public Task A_member_scoped_modify_leaves_the_other_members() => WriteOutcomeScenarios.PartialModifyKeepsOtherMembers(NewScope);

[Test]
public Task A_stored_null_reads_as_null_in_a_member_that_starts_with_a_value() => WriteOutcomeScenarios.StoredNullReadsAsNull(NewScope);

[Test]
public Task A_bulk_load_of_a_taken_key_fails() => WriteOutcomeScenarios.BulkInsertOfTakenKeyFails(NewScope);

Expand Down
Loading
Loading