atom.io/strongly ordered keys

[jeremybanka]

User description

• 🏷️ Canonical
• ♻️ use Canonical type
• 🦋

---

PR Type

Enhancement, Documentation

---

Description

• Replaced Json.Serializable with Canonical for key types across multiple files.
• Renamed Stringified type to stringified and updated relevant functions.
• Added Canonical type definition and updated exports.
• Updated lint:types:watch script concurrency from 20 to 30.
• Added changeset note for breaking change regarding Json.Object.

---

Changes walkthrough 📝

	Relevant files
Enhancement	42 files index.ts Rename `Stringified` to `stringified` and update functions packages/anvl/src/json/index.ts Renamed Stringified type to stringified. Updated parseJson and stringifyJson functions to use stringified. +4/-4      dict.ts Use `Canonical` type for dictionary keys                                  packages/atom.io/data/src/dict.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical and stringified. +3/-3      find-state.ts Use `Canonical` type for finding state                                      packages/atom.io/ephemeral/src/find-state.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +7/-7      seek-state.ts Use `Canonical` type for seeking state                                      packages/atom.io/immortal/src/seek-state.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +8/-8      create-atom-family.ts Use `Canonical` type in atom family creation                          packages/atom.io/internal/src/families/create-atom-family.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +4/-4      create-readonly-selector-family.ts Use `Canonical` type in readonly selector family creation packages/atom.io/internal/src/families/create-readonly-selector-family.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +2/-2      create-regular-atom-family.ts Use `Canonical` type in regular atom family creation          packages/atom.io/internal/src/families/create-regular-atom-family.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +2/-2      create-selector-family.ts Use `Canonical` type in selector family creation                  packages/atom.io/internal/src/families/create-selector-family.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +4/-4      create-writable-selector-family.ts Use `Canonical` type in writable selector family creation packages/atom.io/internal/src/families/create-writable-selector-family.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +2/-2      dispose-from-store.ts Use `Canonical` type in dispose from store                              packages/atom.io/internal/src/families/dispose-from-store.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +3/-7      find-in-store.ts Use `Canonical` type in find in store                                        packages/atom.io/internal/src/families/find-in-store.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +9/-9      init-family-member.ts Use `Canonical` type in init family member                              packages/atom.io/internal/src/families/init-family-member.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +25/-37  seek-in-store.ts Use `Canonical` type in seek in store                                        packages/atom.io/internal/src/families/seek-in-store.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +11/-10  get-from-store.ts Use `Canonical` type in get from store                                      packages/atom.io/internal/src/get-state/get-from-store.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +3/-3      grow-molecule-in-store.ts Use `Canonical` type in grow molecule in store                      packages/atom.io/internal/src/molecule/grow-molecule-in-store.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +9/-9      tracker-family.ts Use `Canonical` type in family tracker                                      packages/atom.io/internal/src/mutable/tracker-family.ts Replaced Json.Serializable with Canonical for family member keys. Updated type imports to use Canonical. +2/-2      set-into-store.ts Use `Canonical` type in set into store                                      packages/atom.io/internal/src/set-state/set-into-store.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +4/-4      deposit.ts Use `Canonical` type in deposit                                                    packages/atom.io/internal/src/store/deposit.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +3/-3      withdraw.ts Use `Canonical` type in withdraw                                                  packages/atom.io/internal/src/store/withdraw.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +10/-9    index.ts Add `Canonical` type and update exports                                    packages/atom.io/json/src/index.ts Added Canonical type definition. Updated exports to include Canonical. +8/-3      select-json-family.ts Use `Canonical` type in select JSON family                              packages/atom.io/json/src/select-json-family.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +4/-4      StateIndex.tsx Use `Canonical` type in StateIndex                                              packages/atom.io/react-devtools/src/StateIndex.tsx Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +5/-4      parse-state-overloads.ts Use `Canonical` type in parse state overloads                        packages/atom.io/react/src/parse-state-overloads.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +4/-4      use-i.ts Use `Canonical` type in useI hook                                                packages/atom.io/react/src/use-i.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +3/-3      use-json.ts Use `Canonical` type in useJSON hook                                          packages/atom.io/react/src/use-json.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +3/-3      use-o.ts Use `Canonical` type in useO hook                                                packages/atom.io/react/src/use-o.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +3/-3      use-pull-atom-family-member.ts Use `Canonical` type in usePullAtomFamilyMember                    packages/atom.io/realtime-react/src/use-pull-atom-family-member.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +2/-2      use-pull-mutable-family-member.ts Use `Canonical` type in usePullMutableAtomFamilyMember      packages/atom.io/realtime-react/src/use-pull-mutable-family-member.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +2/-2      use-pull-selector-family-member.ts Use `Canonical` type in usePullSelectorFamilyMember            packages/atom.io/realtime-react/src/use-pull-selector-family-member.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +2/-2      custom-socket.ts Rename `Stringified` to `stringified` in custom socket      packages/atom.io/realtime-server/src/ipc-sockets/custom-socket.ts Renamed Stringified type to stringified. Updated StringifiedEvent type to use stringified. +2/-2      realtime-family-provider.ts Use `Canonical` type in realtime family provider                  packages/atom.io/realtime-server/src/realtime-family-provider.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +3/-2      realtime-mutable-family-provider.ts Use `Canonical` type in realtime mutable family provider  packages/atom.io/realtime-server/src/realtime-mutable-family-provider.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +2/-2      realtime-continuity.ts Use `Canonical` type in realtime continuity                            packages/atom.io/realtime/src/realtime-continuity.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +2/-2      atom.ts Use `Canonical` type in atom definitions                                  packages/atom.io/src/atom.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +12/-12  dispose-state.ts Use `Canonical` type in dispose state                                        packages/atom.io/src/dispose-state.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +2/-2      get-state.ts Use `Canonical` type in get state                                                packages/atom.io/src/get-state.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +4/-4      index.ts Use `Canonical` type in index                                                        packages/atom.io/src/index.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +5/-5      molecule.ts Use `Canonical` type in molecule definitions                          packages/atom.io/src/molecule.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +4/-3      selector.ts Use `Canonical` type in selector definitions                          packages/atom.io/src/selector.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +12/-12  set-state.ts Use `Canonical` type in set state                                                packages/atom.io/src/set-state.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +3/-2      silo.ts Use `Canonical` type in silo definitions                                  packages/atom.io/src/silo.ts Replaced Json.Serializable with Canonical for key types. Updated type imports to use Canonical. +4/-4      set-rtx.ts Rename `Stringified` to `stringified` in SetRTX                    packages/atom.io/transceivers/set-rtx/src/set-rtx.ts Renamed Stringified type to stringified. Updated SetRTX class to use stringified. +5/-5
Documentation	1 files perfect-eels-love.md Add changeset for breaking change on `Json.Object`              .changeset/perfect-eels-love.md - Added changeset note for breaking change regarding `Json.Object`. +5/-0
Configuration changes	1 files package.json Update lint types watch concurrency                                            package.json - Updated `lint:types:watch` script concurrency from 20 to 30. +1/-1

---

💡 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 11, 2024 4:39am
wayfarer-quest	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 11, 2024 4:39am

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: 16665fedfa703c0d7cc85875ec6139fdc19d1a3c

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 | Minor |

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: 4 🔵🔵🔵🔵⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Key issues to review Type Consistency The type `Canonical` is used extensively across the PR to replace `Json.Serializable`. Ensure that the `Canonical` type definition aligns with the intended use cases and constraints previously handled by `Json.Serializable`. Type Consistency Similar to `atom.ts`, verify that the `Canonical` type is correctly implemented and that it covers all necessary cases for selector families.

[github-actions[bot]]

PR Code Suggestions ✨

Category	Suggestion	Score
Error handling	Add error handling to the JSON parsing function to manage invalid input ___ **Ensure that the parseJson function properly handles the case where the input string does not represent a valid JSON object. This can be done by wrapping the JSON.parse call in a try-catch block to catch any potential errors and handle them appropriately.** [packages/anvl/src/json/index.ts [5-7]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-9baa9e35ea87cbb943e05553a714ee5db89adceb8db743db7046c3dcd2b3bd94R5-R7) ```diff export const parseJson = >( str: S | string, -): S extends stringified ? J : Json.Serializable => JSON.parse(str) +): S extends stringified ? J : Json.Serializable => { + try { + return JSON.parse(str); + } catch (error) { + console.error("Failed to parse JSON:", error); + return null; // or throw an error, depending on desired behavior + } +} ``` Suggestion importance[1-10]: 10 Why: Adding error handling to the JSON parsing function is crucial for robustness, as it prevents the application from crashing due to malformed JSON input.	10
Best practice	Implement error handling in the selectorFamily function ___ **Add error handling in the selectorFamily function to manage exceptions or errors that may occur during the get or set operations.** [packages/atom.io/src/selector.ts [87-88]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-5a6b3bc499ec325f1fdea52698e73b551742a2d4f748332d27475c171f815e47R87-R88) ```diff export function selectorFamily( options: WritableSelectorFamilyOptions, -): WritableSelectorFamilyToken +): WritableSelectorFamilyToken { + try { + // implementation + } catch (error) { + console.error("Error in selectorFamily:", error); + throw error; + } +} ``` Suggestion importance[1-10]: 8 Why: Adding error handling is important for robustness and debugging, making this a valuable improvement to the function.	8
	Rename the type to start with an uppercase letter for consistency ___ **Consider renaming the type stringified to Stringified to maintain consistency with TypeScript's naming conventions for types, which typically start with an uppercase letter.** [packages/anvl/src/json/index.ts [9]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-9baa9e35ea87cbb943e05553a714ee5db89adceb8db743db7046c3dcd2b3bd94R9-R9) ```diff -export type stringified = string & { __json: J } +export type Stringified = string & { __json: J } ``` Suggestion importance[1-10]: 7 Why: Renaming the type to follow TypeScript's naming conventions improves code readability and maintainability, although it is a minor change.	7
	Ensure the 'key' parameter is mandatory ___ **To enhance type safety and ensure that the key parameter is always provided when necessary, consider making the Key parameter mandatory in all function signatures by removing the default to undefined.** [packages/atom.io/internal/src/families/seek-in-store.ts [42-46]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-199e321d47d17eb17a2862f6d58c6d2a8a5bb53c7acbd9234ce2bbb0b201c172R42-R46) ```diff export function seekInStore( token: RegularAtomFamilyToken, - key: Key = undefined, + key: Key, store: Store, ): RegularAtomToken | undefined ``` Suggestion importance[1-10]: 7 Why: Ensuring the 'key' parameter is mandatory improves type safety and prevents potential issues with missing keys, which is a good practice.	7
	Include a validation function for the key in atom family options ___ **Refactor the RegularAtomFamilyOptions and MutableAtomFamilyOptions to include a validation function for the key to ensure it meets specific criteria or constraints.** [packages/atom.io/src/atom.ts [65-69]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-1b18eaa66e66bd13d179fb4e02295c11376b9d25b3be22812b2d6e1993e46f16R65-R69) ```diff export type RegularAtomFamilyOptions = { key: string default: T | ((key: K) => T) effects?: (key: K) => AtomEffect[] + validateKey?: (key: K) => boolean } ``` Suggestion importance[1-10]: 7 Why: Adding a validation function for the `key` can help ensure data integrity and prevent errors, making it a good practice for maintaining code quality.	7
Type safety	Modify the return type to explicitly handle undefined values ___ **Ensure that the dict function's return type explicitly handles the possibility of undefined or null values, which might be returned if the findState function does not find a matching state.** [packages/atom.io/data/src/dict.ts [10-20]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-fd81617099fc6b9662685e6403c1b59ccfbd867a74192e14283edc84d1ccc122R10-R20) ```diff export function dict( findState: | AtomIO.ReadonlySelectorFamilyToken | AtomIO.RegularAtomFamilyToken -): AtomIO.ReadonlySelectorToken<{ [K in stringified]: State }> { +): AtomIO.ReadonlySelectorToken<{ [K in stringified]: State | undefined }> { return createStandaloneSelector({ key: `${findState.key}Dict`, get: ({ get }) => { const state = get(findState); - return { [state.key]: state }; + return { [state.key]: state ?? undefined }; }, }); } ``` Suggestion importance[1-10]: 8 Why: Modifying the return type to handle undefined values enhances type safety and prevents potential runtime errors, which is important for robust code.	8
Enhancement	Add a constraint to ensure non-null keys ___ **Consider adding a generic constraint to ensure that K extends Canonical and is not null or undefined. This can help prevent runtime errors when keys are expected to be non-null.** [packages/atom.io/internal/src/families/seek-in-store.ts [42-46]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-199e321d47d17eb17a2862f6d58c6d2a8a5bb53c7acbd9234ce2bbb0b201c172R42-R46) ```diff -export function seekInStore( +export function seekInStore, Key extends K>( token: RegularAtomFamilyToken, key: Key, store: Store, ): RegularAtomToken | undefined ``` Suggestion importance[1-10]: 8 Why: Adding a constraint to ensure non-null keys enhances type safety and prevents potential runtime errors, which is a significant improvement.	8
	Add a default value or factory function for the key parameter in the useJSON function ___ **Consider adding a default value or a factory function for the key parameter in the useJSON function to handle cases where key might not be provided or needs a default initialization.** [packages/atom.io/react/src/use-json.ts [20]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-7a541aeda2a521e937dd5f7621ecb8867ad76db10cad0ad5aeca0d5ad0000ea6R20-R20) ```diff -export function useJSON(token: MutableAtomFamilyToken, key: Key): Serializable +export function useJSON(token: MutableAtomFamilyToken, key: Key = defaultKey()): Serializable ``` Suggestion importance[1-10]: 5 Why: Adding a default value or factory function for the `key` parameter can improve robustness, but it is not critical and may not be necessary depending on the use case.	5
Maintainability	Refactor to reduce code duplication by using a generic helper function ___ **Refactor the findState functions to reduce code duplication by creating a generic helper function that handles the common logic.** [packages/atom.io/ephemeral/src/find-state.ts [40-65]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-ef73a9ce2ee005c00ea520d72f3424327eaba278cb328adb5d00327438cb62a4R40-R65) ```diff +function findStateHelper( + token: Token, + key: Key, +): ReturnToken { + // common logic here +} export function findState( token: RegularAtomFamilyToken, key: Key, -): RegularAtomToken +): RegularAtomToken { + return findStateHelper, RegularAtomToken>(token, key); +} export function findState( token: WritableSelectorFamilyToken, key: Key, -): WritableSelectorToken +): WritableSelectorToken { + return findStateHelper, WritableSelectorToken>(token, key); +} ... ``` Suggestion importance[1-10]: 6 Why: Refactoring to reduce code duplication improves maintainability and readability, but it is not as critical as other changes.	6
	Simplify function signature by using a single generic type for keys ___ **Refactor the function to use a single generic type for K and Key to simplify the function signature and avoid redundancy.** [packages/atom.io/internal/src/families/seek-in-store.ts [48-52]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-199e321d47d17eb17a2862f6d58c6d2a8a5bb53c7acbd9234ce2bbb0b201c172R48-R52) ```diff -export function seekInStore( +export function seekInStore( token: AtomFamilyToken, - key: Key, + key: K, store: Store, ): AtomToken | undefined ``` Suggestion importance[1-10]: 6 Why: Simplifying the function signature by using a single generic type for keys improves maintainability and readability, though it is a minor improvement.	6
Performance	Cache instances in the spawn method to improve performance ___ **Optimize the spawn method in CtorToolkit by caching instances based on keys to avoid redundant instantiations.** [packages/atom.io/src/molecule.ts [57-60]](https://github.com/jeremybanka/wayforge/pull/2384/files#diff-a9225f960ed0f6fe0eb3b43a57433d9b2c2ff7888f6832b22595890f34eab990R57-R60) ```diff spawn( family: MoleculeFamilyToken, key: Key, ...params: MoleculeParams -): InstanceType +): InstanceType { + const cacheKey = `${family.key}-${key}`; + if (!this.cache[cacheKey]) { + this.cache[cacheKey] = new family(...params); + } + return this.cache[cacheKey]; +} ``` Suggestion importance[1-10]: 6 Why: Caching instances can improve performance by avoiding redundant instantiations, but it may add complexity and should be carefully considered.	6

[coveralls]

coverage: 91.54% (+0.02%) from 91.522% when pulling 16665fedfa703c0d7cc85875ec6139fdc19d1a3c on atom.io/strongly-ordered-keys into cb6912e45d7099e4a48fb3dfa228a3c7239dff7c on main.