refactor: rename Molecule to Selector

src/charm/src/computed.luau

@@ -1,21 +1,20 @@
 local atom = require(script.Parent.atom)
 local store = require(script.Parent.store)
 local types = require(script.Parent.types)
-type Atom<T> = types.Atom<T>
 type AtomOptions<T> = types.AtomOptions<T>
-type Molecule<T> = types.Molecule<T>
+type Selector<T> = types.Selector<T>
 
 --[=[
 	Creates a read-only atom that derives its state from one or more atoms.
 	Used to avoid unnecessary recomputations if multiple listeners depend on
-	the same molecule.
+	the same atoms.
 
-	@param molecule The function that produces the state.
+	@param callback The function that produces the state.
 	@param options Optional configuration.
 	@return A new read-only atom.
 ]=]
-local function computed<T>(molecule: Molecule<T>, options: AtomOptions<T>?): Molecule<T>
+local function computed<T>(callback: Selector<T>, options: AtomOptions<T>?): Selector<T>
-	local dependencies, state = store.capture(molecule)
+	local dependencies, state = store.capture(callback)
 	local computedAtom = atom(state, options)
 	local computedRef = setmetatable({ current = computedAtom }, { __mode = "v" })
 
@@ -24,7 +23,7 @@ local function computed<T>(molecule: Molecule<T>, options: AtomOptions<T>?): Mol
 
 		if computedAtom then
 			store.disconnect(dependencies, listener)
-			dependencies, state = store.capture(molecule)
+			dependencies, state = store.capture(callback)
 			store.connect(dependencies, listener, computedAtom)
 			computedAtom(state)
 		end

src/charm/src/effect.luau

@@ -9,7 +9,7 @@ type Cleanup = () -> ()
 	@param callback The function to run.
 	@return A function that unsubscribes the callback.
 ]=]
-local function effect(callback: () -> (() -> ())?): () -> ()
+local function effect(callback: () -> Cleanup?): Cleanup
 	local dependencies, cleanup = store.capture(callback)
 	local disconnected = false
 

src/charm/src/init.luau

@@ -8,7 +8,8 @@ local subscribe = require(script.subscribe)
 local types = require(script.types)
 
 export type Atom<State> = types.Atom<State>
-export type Molecule<State> = types.Molecule<State>
+export type Molecule<State> = types.Selector<State>
+export type Selector<State> = types.Selector<State>
 export type SyncPayload = types.SyncPayload
 
 return {

src/charm/src/mapped.luau

@@ -3,12 +3,12 @@ local effect = require(script.Parent.effect)
 local store = require(script.Parent.store)
 local types = require(script.Parent.types)
 type Atom<T> = types.Atom<T>
-type Molecule<T> = types.Molecule<T>
+type Selector<T> = types.Selector<T>
 
 type Map =
-	(<K0, V0, K1, V1>(fn: Molecule<{ [K0]: V0 }>, mapper: (V0, K0) -> (V1?, K1)) -> Molecule<{ [K1]: V1 }>)
+	(<K0, V0, K1, V1>(fn: Selector<{ [K0]: V0 }>, mapper: (V0, K0) -> (V1?, K1)) -> Selector<{ [K1]: V1 }>)
-	& (<K0, V0, V1>(fn: Molecule<{ [K0]: V0 }>, mapper: (V0, K0) -> V1?) -> Molecule<{ [K0]: V1 }>)
+	& (<K0, V0, V1>(fn: Selector<{ [K0]: V0 }>, mapper: (V0, K0) -> V1?) -> Selector<{ [K0]: V1 }>)
-	& (<K0, V0, K1, V1>(fn: Molecule<{ [K0]: V0 }>, mapper: (V0, K0) -> (V1?, K1?)) -> Molecule<{ [K1]: V1 }>)
+	& (<K0, V0, K1, V1>(fn: Selector<{ [K0]: V0 }>, mapper: (V0, K0) -> (V1?, K1?)) -> Selector<{ [K1]: V1 }>)
 
 --[=[
 	Maps each entry in the atom's state to a new key-value pair. If the `mapper`
@@ -16,11 +16,11 @@ type Map =
 	When the atom changes, the `mapper` is called for each entry in the state
 	to compute the new state.
 	
-	@param molecule The atom or molecule to map.
+	@param callback The atom or selector to map.
 	@param mapper The function that maps each entry.
 	@return A new atom with the mapped state.
 ]=]
-local function mapped<K0, V0, K1, V1>(molecule: Molecule<{ [K0]: V0 }>, mapper: (V0, K0) -> (V1?, K1?)): Molecule<{ [K1]: V1 }>
+local function mapped<K0, V0, K1, V1>(callback: Selector<{ [K0]: V0 }>, mapper: (V0, K0) -> (V1?, K1?)): Selector<{ [K1]: V1 }>
 	local mappedAtom = atom({})
 	local mappedAtomRef = setmetatable({ current = mappedAtom }, { __mode = "v" })
 	local prevMappedItems: { [K1]: V1 } = {}
@@ -31,7 +31,7 @@ local function mapped<K0, V0, K1, V1>(molecule: Molecule<{ [K0]: V0 }>, mapper:
 			return unsubscribe()
 		end
 
-		local items = molecule()
+		local items = callback()
 		local mappedItems = table.clone(store.peek(mappedAtomRef.current))
 		local mappedKeys = {}
 

src/charm/src/observe.luau

@@ -1,6 +1,6 @@
 local effect = require(script.Parent.effect)
 local types = require(script.Parent.types)
-type Molecule<T> = types.Molecule<T>
+type Selector<T> = types.Selector<T>
 
 local function noop() end
 
@@ -13,7 +13,7 @@ local function noop() end
 	@param factory The function that tracks the lifecycle of each item.
 	@return A function that unsubscribes all instances.
 ]=]
-local function observe<K, V>(molecule: Molecule<{ [K]: V }>, factory: (value: V, key: K) -> (() -> ())?): () -> ()
+local function observe<K, V>(molecule: Selector<{ [K]: V }>, factory: (value: V, key: K) -> (() -> ())?): () -> ()
 	local connections: { [K]: () -> () } = {}
 
 	local unsubscribe = effect(function()

src/charm/src/subscribe.luau

@@ -1,6 +1,6 @@
 local store = require(script.Parent.store)
 local types = require(script.Parent.types)
-type Molecule<T> = types.Molecule<T>
+type Selector<T> = types.Selector<T>
 
 --[=[
 	Subscribes to changes in the given atom or molecule. The callback is
@@ -11,7 +11,7 @@ type Molecule<T> = types.Molecule<T>
 	@param callback The function to call when the state changes.
 	@return A function that unsubscribes the callback.
 ]=]
-local function subscribe<T>(molecule: Molecule<T>, callback: (state: T, prev: T) -> ()): () -> ()
+local function subscribe<T>(molecule: Selector<T>, callback: (state: T, prev: T) -> ()): () -> ()
 	local dependencies, state = store.capture(molecule)
 	local disconnected = false
 

src/charm/src/types.luau

@@ -9,7 +9,7 @@ export type WeakMap<K, V> = typeof(setmetatable({} :: { [K]: V }, { __mode = "k"
 	@param state The next state or a function that produces the next state.
 	@return The current state, if no arguments are provided.
 ]=]
-export type Atom<T> = (() -> T) & (state: T | (T) -> T) -> T
+export type Atom<T> = (state: (T | (T) -> T)?) -> T
 
 --[=[
 	A function that depends on one or more atoms and produces a state. Can be
@@ -18,7 +18,7 @@ export type Atom<T> = (() -> T) & (state: T | (T) -> T) -> T
 	@template State The type of the state.
 	@return The current state.
 ]=]
-export type Molecule<T> = () -> T
+export type Selector<T> = () -> T
 
 --[=[
 	Optional configuration for creating an atom.