117 lines
5 KiB
TypeScript
117 lines
5 KiB
TypeScript
|
|
import React from 'react';
|
|
import { ContentPage } from '../../components/ContentPage';
|
|
import { ApiSection } from '../../types';
|
|
|
|
const mapApi: ApiSection[] = [
|
|
{
|
|
title: 'Chemical.Map',
|
|
description: 'Creates a reactive dictionary (table with string or mixed keys). Changes to the map structure or its values can trigger updates in dependent Computeds and Effects. For reactivity of individual values within the map, those values would typically be Chemical.Value objects if fine-grained updates are needed, though this pattern is more common within Reactions.',
|
|
entries: [
|
|
{
|
|
signature: 'Chemical.Map<{[K]: V}>(initialObject: {[K]: V}): Map<{[K]: V}>',
|
|
description: 'Constructs a new reactive Map object.',
|
|
parameters: [
|
|
{ name: 'initialObject', type: '{[K]: V}', description: 'The initial dictionary/map (plain Lua table) to store.' },
|
|
],
|
|
returns: { type: 'Map<{[K]: V}>', description: 'A new Map object.' },
|
|
example: `
|
|
local Chemical = require(game.ReplicatedStorage.Chemical)
|
|
local Map = Chemical.Map
|
|
local Table = Chemical.Table -- if needed for values
|
|
|
|
local playerConfig = Map({
|
|
name = "Hero",
|
|
level = 10, -- Store primitives directly
|
|
inventory = {"sword", "shield"} -- Store plain tables directly
|
|
})
|
|
`,
|
|
notes: "Chemical.Map is best used with primitive values or plain tables as its direct values. If you need a map of reactive objects, consider if a Reaction is more appropriate, especially for networked state."
|
|
},
|
|
],
|
|
},
|
|
{
|
|
title: 'Map Methods',
|
|
entries: [
|
|
{
|
|
signature: 'map:get(): {[K]: V}',
|
|
description: 'Retrieves the current dictionary/map. If called within a Computed or Effect, it establishes a dependency on this Map.',
|
|
returns: { type: '{[K]: V}', description: 'The current dictionary/map.' },
|
|
example: `
|
|
local Chemical = require(game.ReplicatedStorage.Chemical)
|
|
local Map = Chemical.Map
|
|
|
|
local settings = Map({ volume = 0.8, difficulty = "hard" })
|
|
local currentSettings = settings:get()
|
|
-- currentSettings is { volume = 0.8, difficulty = "hard" }
|
|
`,
|
|
},
|
|
{
|
|
signature: 'map:set(newObject: {[K]: V})',
|
|
description: 'Replaces the entire dictionary/map with a new one. This is a significant change and will notify all dependents.',
|
|
parameters: [
|
|
{ name: 'newObject', type: '{[K]: V}', description: 'The new dictionary/map (plain Lua table) to set.' },
|
|
],
|
|
example: `
|
|
local Chemical = require(game.ReplicatedStorage.Chemical)
|
|
local Map = Chemical.Map
|
|
|
|
local config = Map({ enabled = true })
|
|
config:set({ enabled = false, mode = "advanced" })
|
|
-- config:get() is now { enabled = false, mode = "advanced" }
|
|
`,
|
|
},
|
|
{
|
|
signature: 'map:key(key: K, value?: V)',
|
|
description: 'Sets or removes a key-value pair in the map. If `value` is provided, the key is set to this value. If `value` is `nil`, the key is removed from the map.',
|
|
parameters: [
|
|
{ name: 'key', type: 'K', description: 'The key to set or remove.' },
|
|
{ name: 'value', type: 'V?', description: 'The value to set for the key. If nil, the key is removed.' },
|
|
],
|
|
example: `
|
|
local Chemical = require(game.ReplicatedStorage.Chemical)
|
|
local Map = Chemical.Map
|
|
|
|
local user = Map({ name = "Alice" })
|
|
user:key("age", 30) -- user:get() is now { name = "Alice", age = 30 }
|
|
user:key("name", nil) -- user:get() is now { age = 30 }
|
|
user:key("status", "active") -- user:get() is { age = 30, status = "active" }
|
|
`,
|
|
},
|
|
{
|
|
signature: 'map:clear(cleanup?: (value: V) -> ())',
|
|
description: 'Removes all key-value pairs from the map. An optional cleanup function can be provided, which will be called for each value (recursively for nested plain tables).',
|
|
parameters: [
|
|
{ name: 'cleanup', type: '((value: V) -> ())?', description: 'Optional function to call for each value being cleared.'}
|
|
],
|
|
example: `
|
|
local Chemical = require(game.ReplicatedStorage.Chemical)
|
|
local Map = Chemical.Map
|
|
|
|
local data = Map({ a = 1, b = { c = 2 } })
|
|
data:clear(function(value)
|
|
print("Cleaning up:", value) -- For 'a', value is 1. For 'b', value is {c=2}. For 'c', value is 2.
|
|
end)
|
|
-- data:get() is now {}
|
|
`,
|
|
notes: "If values within the map are Chemical stateful objects (e.g., if the Map is part of a Reaction), their own :destroy() methods should be managed by the Reaction's destruction or explicit calls, not typically by Map:clear's cleanup."
|
|
},
|
|
{
|
|
signature: 'map:destroy()',
|
|
description: 'Destroys the Map object and its resources. If the Map is part of a Reaction, this destruction is typically handled by the Reaction itself.',
|
|
example: `
|
|
local Chemical = require(game.ReplicatedStorage.Chemical)
|
|
local Map = Chemical.Map
|
|
|
|
local sessionData = Map({ id = "xyz", expires = os.time() + 3600 })
|
|
-- ...
|
|
sessionData:destroy()
|
|
`,
|
|
},
|
|
],
|
|
},
|
|
];
|
|
|
|
export const MapPage: React.FC = () => {
|
|
return <ContentPage title="Chemical.Map" sections={mapApi} />;
|
|
};
|