LearnNewsExamplesServices
Frontmatter
id8085
titleRefactor Store: Default to eager record init for DX and enhance JSDoc
stateClosed
labels
documentationdeveloper-experienceairefactoring
assigneestobiu
createdAtDec 11, 2025, 2:31 AM
updatedAtDec 11, 2025, 2:51 AM
githubUrlhttps://github.com/neomjs/neo/issues/8085
authortobiu
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtDec 11, 2025, 2:51 AM

Refactor Store: Default to eager record init for DX and enhance JSDoc

Closed v11.17.0 documentationdeveloper-experienceairefactoring
tobiu
tobiu commented on Dec 11, 2025, 2:31 AM

Refactor Neo.data.Store to default add() and insert() to eager record initialization (init=true) and enhance JSDoc.

Reasoning (DX): The previous default behavior of add() returning raw data objects (lazy loading) was a common "gotcha" for developers, requiring a second step (store.get(id)) to obtain a usable Model instance. By changing the default init parameter to true, store.add(data) now returns fully instantiated records by default, which is the expected behavior in most standard use cases.

Changes:

  1. Neo.data.Store:
    • add(item, init=true): Defaults to eager initialization.
    • insert(index, item, init=true): Defaults to eager initialization.
    • Internal usages (afterSetData, sort) explicitly use init=false to preserve performance for bulk operations.
  2. examples/grid/bigData/MainStore.mjs:
    • Explicitly uses init=false ("Turbo Mode") to ensure the 100k row benchmark continues to use the performant lazy-loading chunking mechanism.

Documentation Enhancement: The JSDoc for add and insert in Neo.data.Store needs to be significantly enhanced to clearly explain:

  • The difference between init=true (eager, returns Records) and init=false (lazy, returns raw data / count).
  • The performance implications (use init=false for bulk loading).
  • The return type variations (Number vs Array).
tobiu added the documentation label on Dec 11, 2025, 2:31 AM
tobiu added the developer-experience label on Dec 11, 2025, 2:31 AM
tobiu added the ai label on Dec 11, 2025, 2:31 AM
tobiu added the refactoring label on Dec 11, 2025, 2:31 AM
tobiu assigned to @tobiu on Dec 11, 2025, 2:32 AM
tobiu referenced in commit 0abef4c - "Refactor Store: Default to eager record init for DX and enhance JSDoc #8085" on Dec 11, 2025, 2:51 AM
tobiu closed this issue on Dec 11, 2025, 2:51 AM