CItem<T> class final

A single typed record in an AtCollection. Wraps an application's domain object of type T together with Atsign Protocol object metadata:

  • owner — the atSign that wrote this item. Only the owner can mutate or delete it; other atSigns see read-only cached copies. item.owner == item.self is the ownership test the library uses internally.

  • id — a per-owner unique identifier (not globally unique). Alice and Bob can each have an item with id abc — they're distinct records. Combine (owner, id) to identify an item globally.

  • obj — the app-defined payload. For collections whose T is registered via AtCollection.registerFactory, incoming envelopes are rehydrated into typed instances.

  • sharedWith — the distribution list: atSigns who each receive their own cached copy of this item. Mutable — edit it then call AtCollection.update to persist the diff.

  • createdAt / expiresAt / availableAt — lifecycle timestamps. expiresAt is mutable (the owner can extend or shorten an item's TTL); availableAt schedules recipient-copy visibility (time-to-birth).

  • readBy / readBySnapshot / wasMarkedReadByMe / markReadByMe — the read-receipt surface. See the AtCollection class-level doc for the receipt model overview.

Construction is always via AtCollection.draft or AtCollection.create; the constructor is private so every CItem is bound to a collection it can delegate to for reads, sub- collection resolution, and event streaming.

Mutability. sharedWith, expiresAt, and availableAt are intentionally mutable so the natural "fetch, mutate, persist" idiom works without a separate copy step. Mutate them in place, then call AtCollection.update to persist. Internally obj is also assigned-to during rehydrate; app code should treat the rehydrated value as the canonical state and not mutate the rehydrated obj reference itself — model objects implement toJson / fromJson and the round-trip is the supported path.

Available extensions

Properties

ancestors → List<({String id, Atsign owner})>
Root-to-direct-parent chain for a sub-collection item. Empty for items in a root collection. Each entry combines the envelope-persisted parentOwners at the same index with the id of that ancestor, which is recovered from the sub-collection's composed namespace.
no setter
availableAt ↔ DateTime?
Earliest moment at which recipient copies become visible. null means "visible immediately". Mutate before calling AtCollection.update to schedule.
getter/setter pair
collection → AtCollection<T>
no setter
createdAt ↔ DateTime
When this item was first written. Set by AtCollection.draft for new items; read from server metadata on rehydrate.
getter/setter pair
expiresAt ↔ DateTime
Wall-clock expiry. Mutate before calling AtCollection.update to change the item's lifecycle.
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
id → String
The unique identifier, prepended to the collection's namespace when persisted. E.g. if the collection namespace is todos.my_apps then the full persisted key prefix is <id>.todos.my_apps.
final
obj ↔ T
The application's domain object. late final so a not-yet-available placeholder (CItem._placeholder) can omit it — a non-nullable T has no null value, and the scheduler that consumes placeholders never reads obj. Reading it on a placeholder throws.
latefinal
owner → Atsign
The atSign which created this CItem. For example if we are currently @alice, then the owner of a CItem which we create is @alice; the owner of a CItem shared with us by @bob is @bob.
final
parentOwners → List<Atsign>
Root-to-direct-parent owner chain persisted in the envelope. Empty for items in a root collection. Length equals the item's nesting depth for items in a sub-collection. Owner at index i is the ancestor at nesting level i (root-most first).
final
prettyString → String

Available on CItem, provided by the CItemPrettyString extension

no setter
readBy → Future<Set<Atsign>>
The set of atSigns known to have read this item.
no setter
readBySnapshot → Set<Atsign>
Synchronous accessor for the cached reader set; useful for UI draw loops that can't await. Returns an empty set until the first await item.readBy has primed the cache. Event-driven updates keep this in sync thereafter.
no setter
receipts → AtCollection<Map<String, dynamic>>
Shortcut for AtCollection.readReceiptsFor on this item — the reserved __rr sub-collection holding receipts. Use this when you want to query receipts directly (e.g. live counts, custom UI over the receipt timeline):
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
self → Atsign
The atSign this item's collection is acting as — delegates to AtCollection.self. Useful for ownership checks: item.owner == item.self means "I own this item".
no setter
sharedWith → Set<Atsign>
atSigns who receive a copy of this item. Mutable; edit then call AtCollection.update to persist.
final
type ↔ String
The type-tag that drives rehydration. Set automatically by draft from obj.runtimeType.toString() when a factory is registered, otherwise 'binary' for Uint8List or 'n/a' for primitives.
latefinal

Methods

markReadByMe() → Future<void>
Idempotent: if the current atSign has already posted a read receipt for this item, does nothing. Otherwise writes a recipient-only receipt sub-item shared with owner. No-op on self-owned items.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toJson() → Map<String, dynamic>
toString() → String
A string representation of this object.
override
wasMarkedReadByMe() → Future<bool>
True iff the current atSign (self) has already posted a read receipt for this item. Returns true for self-owned items (the owner is trivially "caught up" on their own record).

Operators

operator ==(Object other) → bool
The equality operator.
inherited