atom.io/return token from creation functions

[jeremybanka]

User description

• ♻️ return tokens from family functions
• 🦋

---

PR Type

Enhancement, Tests

---

Description

• Updated various function signatures and return types to use new family tokens (AtomFamilyToken, MutableAtomFamilyToken, RegularAtomFamilyToken, ReadonlySelectorFamilyToken, WritableSelectorFamilyToken).
• Removed unused type imports and definitions.
• Updated test cases to match new function signatures.
• Added changeset note for returning only tokens from atomFamily and selectorFamily.

---

Changes walkthrough 📝

	Relevant files
Enhancement	27 files use-family.ts Update `getFamily` functions to use Internal types              packages/atom.io/__tests__/__util__/use-family.ts Changed Store type import to Internal.Store. Updated function signatures to use Internal.Store. Modified getFamily function to use Internal.ReadableFamily. +11/-10  space-states.ts Remove unused type imports                                                              packages/atom.io/__unstable__/react-explorer/src/space-states.ts - Removed unused type imports. +0/-2      view-states.ts Remove unused type imports                                                              packages/atom.io/__unstable__/react-explorer/src/view-states.ts - Removed unused type imports. +1/-5      realtime-server.ts Update `AtomFamily` type to `AtomFamilyToken`                        packages/atom.io/__unstable__/realtime-server-next/realtime-server.ts Updated AtomFamily type to AtomFamilyToken. Updated function signatures to use AtomFamilyToken. +12/-10  dict.ts Update parameter name and function calls                                  packages/atom.io/data/src/dict.ts Updated parameter name from findState to family. Updated function calls to use family. +4/-4      join.ts Update types to use new family tokens                                        packages/atom.io/data/src/join.ts Updated types to use ReadonlySelectorFamilyToken and RegularAtomFamilyToken. +12/-13  struct-family.ts Update return types to use `RegularAtomFamilyToken`            packages/atom.io/data/src/struct-family.ts - Updated return types to use `RegularAtomFamilyToken`. +2/-2      create-atom-family.ts Update return types to use new family tokens                          packages/atom.io/internal/src/families/create-atom-family.ts Updated return types to use MutableAtomFamilyToken and RegularAtomFamilyToken. +6/-5      create-readonly-selector-family.ts Update return type to use `ReadonlySelectorFamilyToken`    packages/atom.io/internal/src/families/create-readonly-selector-family.ts - Updated return type to use `ReadonlySelectorFamilyToken`. +3/-3      create-regular-atom-family.ts Update return type to use `RegularAtomFamilyToken`              packages/atom.io/internal/src/families/create-regular-atom-family.ts - Updated return type to use `RegularAtomFamilyToken`. +8/-12    create-selector-family.ts Update return types to use new selector family tokens        packages/atom.io/internal/src/families/create-selector-family.ts Updated return types to use WritableSelectorFamilyToken and ReadonlySelectorFamilyToken. +6/-5      create-writable-selector-family.ts Update return type to use `WritableSelectorFamilyToken`    packages/atom.io/internal/src/families/create-writable-selector-family.ts - Updated return type to use `WritableSelectorFamilyToken`. +3/-3      index.ts Add and update type definitions for family tokens                packages/atom.io/internal/src/index.ts Added type definitions for various family tokens. Updated type definitions to use new family tokens. +75/-2    grow-molecule-in-store.ts Update function signatures to use new family tokens            packages/atom.io/internal/src/molecule/grow-molecule-in-store.ts - Updated function signatures to use new family tokens. +27/-17  create-mutable-atom-family.ts Update return type to use `MutableAtomFamilyToken`              packages/atom.io/internal/src/mutable/create-mutable-atom-family.ts - Updated return type to use `MutableAtomFamilyToken`. +3/-3      get-json-family.ts Update import to use `WritableSelectorFamily`                        packages/atom.io/internal/src/mutable/get-json-family.ts - Updated import to use `WritableSelectorFamily`. +2/-1      get-update-family.ts Update import to use `AtomFamily`                                                packages/atom.io/internal/src/mutable/get-update-family.ts - Updated import to use `AtomFamily`. +2/-1      tracker-family.ts Update imports and constructor in `FamilyTracker`                packages/atom.io/internal/src/mutable/tracker-family.ts Updated import to use MutableAtomFamily and RegularAtomFamily. Updated FamilyTracker constructor to use withdraw. +4/-3      store.ts Update imports to use new family tokens                                    packages/atom.io/internal/src/store/store.ts - Updated imports to use new family tokens. +4/-4      withdraw.ts Update imports to use new family tokens                                    packages/atom.io/internal/src/store/withdraw.ts - Updated imports to use new family tokens. +8/-8      attach-timeline-family.ts Update `get` function call in `attach-timeline-family`      packages/atom.io/introspection/src/attach-timeline-family.ts - Updated `get` function call to match new signature. +1/-1      attach-transaction-logs.ts Update `findTransactionUpdateLog` and `get` function call packages/atom.io/introspection/src/attach-transaction-logs.ts Updated findTransactionUpdateLog to transactionUpdateLogAtoms. Updated get function call to match new signature. +2/-2      select-json-family.ts Update function parameters and calls to use `atomFamilyToken` packages/atom.io/json/src/select-json-family.ts Updated function parameters to use atomFamilyToken. Updated function calls to use atomFamilyToken. +18/-17  atom.ts Remove `RegularAtomFamily` and `MutableAtomFamily` type definitions packages/atom.io/src/atom.ts Removed RegularAtomFamily and MutableAtomFamily type definitions. +2/-35    index.ts Remove `WritableFamily` and `ReadableFamily` type definitions packages/atom.io/src/index.ts - Removed `WritableFamily` and `ReadableFamily` type definitions. +1/-10    selector.ts Remove WritableSelectorFamily and ReadonlySelectorFamily type definitions packages/atom.io/src/selector.ts Removed WritableSelectorFamily and ReadonlySelectorFamily type definitions. +1/-26    silo.ts Update return types to use new family tokens                          packages/atom.io/src/silo.ts - Updated return types to use new family tokens. +7/-5
Tests	2 files struct.test.ts Update `setState` function call in tests                                  packages/atom.io/__tests__/public/data/struct.test.ts - Updated `setState` function call to match new signature. +1/-1      mutable-atom.test.ts Update `findFlagsStateByUserId` function call in tests      packages/atom.io/__tests__/public/mutability/mutable-atom.test.ts Updated findFlagsStateByUserId function call to match new signature. +1/-1
Documentation	1 files shy-doors-play.md Add changeset note for token return update                              .changeset/shy-doors-play.md Added changeset note for returning only tokens from atomFamily and selectorFamily. +5/-0

---

💡 PR-Agent usage: Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
atom-io-fyi	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 14, 2024 0:03am
wayfarer-quest	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 14, 2024 0:03am

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: 11ea4482f1bb37f173cc7e737e7b97a3ba315791

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

| Name | Type | | ------- | ----- | | atom.io | Patch |

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions[bot]]

PR Reviewer Guide 🔍

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 PR contains tests

🔒 No security concerns identified

⚡ Key issues to review Type Consistency The function `getFamily` has been updated to use `Internal.Store` instead of `Store`. Ensure that all usages of `getFamily` across the project are updated to pass `Internal.Store` instances. This change could potentially break existing calls if not handled properly. Function Signature Change The function call `setState(piecemealStates.findUserAgeState, 'a', 42)` has been modified. Ensure that the new signature matches the expected usage and that all dependent code is updated accordingly. Function Signature Change The function call `findState(findFlagsStateByUserId, 'my-user-id')` has been modified. Verify that the new usage correctly matches the intended functionality and that related tests are updated. Import Cleanup Unused imports have been removed. Confirm that there are no references to the removed types left in the code that could cause runtime errors. API Changes The method `provide` has been updated to use `AtomFamilyToken` instead of `AtomFamily`. This change affects the method's type signature and could impact how the method is used throughout the application. Function Signature Change The function `dict` has been updated to use new token types. Ensure that all calls to this function are checked for compatibility with the new signatures. Type Changes The types in the `Join` class have been updated to use tokens instead of direct family types. This change could affect type safety and runtime behavior if not properly integrated. Return Type Change The `createAtomFamily` function now returns tokens instead of direct family instances. This change affects how the function's return value is used in the system. Return Type Change The function `createReadonlySelectorFamily` has been updated to return a token instead of a family instance. Verify that all usages of this function properly handle the new return type. Return Type Change The function `createRegularAtomFamily` now returns a token instead of a family instance. Ensure that this change is reflected in all parts of the application that use this function. Return Type Change The `createSelectorFamily` function has been updated to return tokens instead of family instances. This modification affects how the function integrates with the rest of the application. Return Type Change The function `createWritableSelectorFamily` now returns a token instead of a family instance. Confirm that all usages of this function are updated to handle the new return type. Type Definitions New type definitions have been added to the index file. Review these definitions to ensure they are correctly implemented and do not conflict with existing types. Function Signature Change The function `growMoleculeInStore` has been updated to use new token types. Verify that all calls to this function are compatible with the updated signatures. Return Type Change The function `createMutableAtomFamily` now returns a token instead of a family instance. Ensure that this change is properly integrated into the application. Function Signature Change The function `selectJsonFamily` has been updated to use new token types. This change could affect how JSON data is handled in the application.

[github-actions[bot]]

PR Code Suggestions ✨

Category	Suggestion	Score
Possible bug	Correct the invocation of findFlagsStateByUserId to ensure it returns the expected state token ___ **It appears that findState is expected to be a function that returns a state token. Ensure that findState is invoked correctly to obtain the state token.** [packages/atom.io/__tests__/public/mutability/mutable-atom.test.ts [101]](https://github.com/jeremybanka/wayforge/pull/2400/files#diff-dddd54eac289447b2f1d102c5e51204d4c0de17f0d74f4131ee2b36d2e47104eR101-R101) ```diff -const myFlagsState = findState(findFlagsStateByUserId, `my-user-id`) +const myFlagsState = findFlagsStateByUserId(`my-user-id`) ``` Suggestion importance[1-10]: 10 Why: Correcting the invocation of `findFlagsStateByUserId` to ensure it returns the expected state token is crucial for the correct functionality of the code. This suggestion addresses a major bug.	10
	Prevent potential runtime errors by handling null values from store.molecules.get ___ **Add error handling for the case when store.molecules.get(stringKey) returns null, to prevent calling growMoleculeInStore with a null value, which could lead to runtime errors.** [packages/atom.io/json/src/select-json-family.ts [56-58]](https://github.com/jeremybanka/wayforge/pull/2400/files#diff-1064bc5aee5f6ad9e6b71dfa5022dc69b55643e1ee0d1f1b4ae7ed40da8c4907R56-R58) ```diff const molecule = store.molecules.get(stringKey); if (molecule) { const atom = growMoleculeInStore(molecule, atomFamilyToken, store); return transform.toJson(get(atom)); +} else { + throw new Error(`Molecule not found for key "${stringKey}"`); } ``` Suggestion importance[1-10]: 10 Why: The suggestion addresses a potential bug by adding error handling for null values returned from `store.molecules.get`, which could prevent runtime errors.	10
	Add a null check before calling the install method to prevent runtime errors ___ **Consider checking for null before calling install on actualFamily to avoid potential runtime errors if actualFamily is null.** [packages/atom.io/__tests__/__util__/use-family.ts [28-29]](https://github.com/jeremybanka/wayforge/pull/2400/files#diff-7644aed834a0febe4e94a5533b2de2a249fd6a160fce9259bda99e357bcaab28R28-R29) ```diff const actualFamily = Internal.IMPLICIT.STORE.families.get(family.key) -actualFamily?.install(store) +if (actualFamily !== null) { + actualFamily.install(store) +} ``` Suggestion importance[1-10]: 9 Why: Adding a null check before calling the `install` method is a good practice to prevent potential runtime errors. This suggestion addresses a possible bug and improves the robustness of the code.	9
Possible issue	Ensure consistent function call structure by using direct function invocation ___ **Replace the usage of transactionUpdateLogAtoms with a direct function call to transactionUpdateLogAtoms(key) inside the get function to align with the previous implementation and ensure consistency.** [packages/atom.io/introspection/src/attach-transaction-logs.ts [41]](https://github.com/jeremybanka/wayforge/pull/2400/files#diff-b14bde7c78b016d5ff4cd3a8283e465696a5aa06a71579a0da425c9547b46ee6R41-R41) ```diff -get(transactionUpdateLogAtoms, key), +get(transactionUpdateLogAtoms(key)), ``` Suggestion importance[1-10]: 10 Why: The suggestion corrects the function call structure to align with the previous implementation, ensuring consistency and potentially preventing runtime errors.	10
	Validate findUserAgeState and its return before calling setState to ensure correct usage ___ **Ensure that setState is called with a valid state token and parameters. The current implementation may lead to unexpected behavior if findUserAgeState is not a function or does not return a valid state token.** [packages/atom.io/__tests__/public/data/struct.test.ts [38]](https://github.com/jeremybanka/wayforge/pull/2400/files#diff-9ad1b4c2e45f759d7d09601790d9643b33273474b9ffbe488cc62ac46ec6c3e6R38-R38) ```diff -setState(piecemealStates.findUserAgeState, `a`, 42) +if (typeof piecemealStates.findUserAgeState === 'function') { + const stateToken = piecemealStates.findUserAgeState(`a`); + if (stateToken) { + setState(stateToken, 42); + } +} ``` Suggestion importance[1-10]: 8 Why: Validating `findUserAgeState` and its return value before calling `setState` ensures correct usage and prevents unexpected behavior. This suggestion addresses a possible issue and improves code reliability.	8
Enhancement	Add error handling for null or undefined results from transform.toJson ___ **Consider handling the case where transform.toJson(get(existingState)) might return null or undefined, which could lead to unexpected behavior or errors in the application.** [packages/atom.io/json/src/select-json-family.ts [51-53]](https://github.com/jeremybanka/wayforge/pull/2400/files#diff-1064bc5aee5f6ad9e6b71dfa5022dc69b55643e1ee0d1f1b4ae7ed40da8c4907R51-R53) ```diff if (existingState) { - return transform.toJson(get(existingState)) + const result = transform.toJson(get(existingState)); + if (result !== undefined && result !== null) { + return result; + } + throw new Error('Failed to transform existing state to JSON.'); } ``` Suggestion importance[1-10]: 9 Why: This suggestion adds necessary error handling to prevent unexpected behavior or errors when `transform.toJson` returns null or undefined, improving the robustness of the code.	9
	Add validation for atomFamilyToken.key to prevent potential runtime errors ___ **Replace the direct assignment of atomFamilyToken.key with a function or method that ensures the key exists and is valid, to prevent runtime errors due to undefined or invalid keys.** [packages/atom.io/json/src/select-json-family.ts [46]](https://github.com/jeremybanka/wayforge/pull/2400/files#diff-1064bc5aee5f6ad9e6b71dfa5022dc69b55643e1ee0d1f1b4ae7ed40da8c4907R46-R46) ```diff -key: `${atomFamilyToken.key}:JSON`, +key: `${validateKey(atomFamilyToken.key)}:JSON`, ``` Suggestion importance[1-10]: 8 Why: Adding validation for `atomFamilyToken.key` is a good enhancement to prevent potential runtime errors due to undefined or invalid keys.	8
	Modify the key property format to ensure it correctly represents its namespace and purpose ___ **Ensure that the key property is correctly set for the selector. The current implementation may not correctly reflect the intended key for the selector.** [packages/atom.io/data/src/dict.ts [23]](https://github.com/jeremybanka/wayforge/pull/2400/files#diff-fd81617099fc6b9662685e6403c1b59ccfbd867a74192e14283edc84d1ccc122R23-R23) ```diff -key: `${family.key}Dict`, +key: `${family.key}.Dict`, ``` Suggestion importance[1-10]: 6 Why: Modifying the `key` property format to ensure it correctly represents its namespace and purpose is a minor enhancement that improves code readability and maintainability.	6

[coveralls]

coverage: 91.705% (+0.08%) from 91.627% when pulling 11ea4482f1bb37f173cc7e737e7b97a3ba315791 on atom.io/return-token-from-creation-functions into 5a733638f669fc82283a5b45f8f9d25338c4f1f6 on main.