Update - STATE

[alyhxn]

@todo

playproject-io/playproject-io.github.io#30

---

• Update - STATE
  • Bugs to be fixed
    • Increase of instances on reload
      • @input 📦 discord ibrar-worklog-4
    • Errors faced by a newbie
      • @input 📦 flamingo_wallet_commit
  • Add new features
  • root module can only call statedb(...) after it called statedb.admin(..), otherwise statedb(...) throws
  • Smart way of tracking changes during override
    • @input 📦 discord alixhn-worklog-280
  • define admin revokable { $ref: 'drive://invitecode' } or { $ref: drivelink } scoped to specific datasets, writable or readonly
    • @input 📦 discord feedback2 for worklog-275 from given
    • @input 📦 discord feedback5 for worklog-276 from given
  • allow to use drive references (e.g. {$ref:path}) in arguments or options for instances defined in fallbacks
    • It does not mean that we provide all data through a component drive, but that a component instead has additional writable and/or readonly drives in addition to its
  • refactor all examples and projects using STATE to use the new shim
  • verify all STATE fallback/override data
    • @input 📦 discord feedback4 for worklog-276 from given
  • make a growing list of test cases to prevent regression
  • review docs and update docs for all features of STATE.js
    • add a growing list of use cases and how to solve them using the STATE module
      • @input 📦 technique description from given
      • document techniques we discover, e.g. for using sdb.get_sub in page.js to pair components with editor in container views
    • we will have the drives, but in parallel we try to make them unneeded by improving error logs to guide developers
    • all error messages are short, so docs will include more description and code example snippets as needed
    • document the statedb.admin property and what every field or method does
      • admin.status.dataset.drive
      • admin.status.dataset.drive.list('', node)
      • admin.status.db
    • document sdb property if there is anything missing
      • document sdb.get_sub if it hasn't happened yet
    • update other things if they are missing or new features that haven't been documented yet
  • revamp/refactor STATE module to clean it up and improve readability, maintainability and performance where possible
  • @output 📦 STATE_v0.0.?
    • next Create - theme_widget playproject-io.github.io#21

[alyhxn]

Tasks - 2025.07.24

• Update - STATE_v0.0.24
  • @input 📦 STATE_v0.0.24 from comment
  • Admin pluggable storage & hooks - 1h
  • Allow overridden nodes to use the files of override ($ref_id) - 5h
  • allow to define drive data via properties such as 'data/style.json' - 4h
  • Non-state sub modules should not be required to be defined in the fallback - 30min
  • Debugging - 3h
  • Logged tasks - 20min
  • Recorded Worklog - 15min
  • @outputs📦 STATE_v0.0.25

---

Worklog

worklog-279

[serapath]

feedback 2025.07.25

Great worklog. Thank you :-)

Here is some feedback, but i also shared some more on discord.

Looking at the code, i see:

  console.log(await drive.put('lang/en-uk.json', { links: ['Home', 'About', 'Contact'] }))
  console.log(await drive.get('lang/en-uk.json'))

I assume this was mostly a test and doesnt really belong here.

     data.drive['theme/'] = {
        'style.css': {
          $ref: 'btn.css',
          address
        }
      }

This is confusing and i'm wondering what address does here, but will check the worklog - again, like i said on discord already, we need proper updates of documentation.

Also, i assume that this:

const { sdb, io } = statedb(fallback_module, localdb)

is optional and can also be skipped which means things fall back to the internal one.

Also, it doesnt seem right in general.

 function statedb (fallback, imported_db = localdb) {
    if(!db) {
      db = imported_db()
      // Version check and initialization
      status.fallback_check = Boolean(check_version())
      status.fallback_check && db.add(['playproject_version'], VERSION)
    }
    // ...

This suggests that evvery module can call statedb with its custom db instance, but that is not what i meant. The idea was to allow .admin which is only available one to the root module component and not for any subs later on, to define those hooks etc... and they apply for all database sub instances etc...

Its a devtools/admin feature and not one that a module or component developer uses inside their own module component.

Basically, your temporary notes say it already:

> the first module should also be able to immediately register callbacks for statedb.admin.on(callback), where the callback gets called with { type, data } objects every time an sdb or io object gets created or used by any module or instance and data should include the modulepath and type should describe what kind of usage it is 🙂

- Who defines the type?

So, every sdb is created with statedb(...) for a module or get(sid) for an instance, it would trigger. the type would be e.g. load and the data would be e.g. <modulepath> and then every time io is used to connect or sdb.drive is used to modify e.g. (put/del) files and folders etc... this should trigger an update too.

Why? Because this feature can be used to actually display the real theme widget data in the graph explorer and show changes too regardless of where they happen.

[alyhxn]

Tasks - 2025.08.19

• Update - STATE_v0.0.25
  • Revamp the STATE - 3h
  • Removed the address when defining a $ref for an overrided node - 1h
  • Added sdb.get to access readonly sub drives - 1h30min
  • Updated the examples to use the new bundling architecture - 4h
  • Logged tasks - 5min
  • Recorded Worklog - 10min
  • @outputs:
    • 📦 STATE_v0.0.26
    • 📦 datashell_v0.0.1

---

Worklog

worklog-280

---

Proposals

• Do you mean this whole line is optional

const { sdb, io } = statedb(fallback_module, localdb)

• Use statedb.admin instead of statedb for db definition. Needs discussion
• Define statedb.admin.on for callbacks which executes upon all major actions inside STATE
• Find a smart way to know which file was changed or introduced during the override.

[serapath]

feedback 2025.08.20

Great. Thanks. Lets continue and discuss proposals on discord :-)

[alyhxn]

Tasks - 2925.08.25

• Update - STATE_v0.0.26
  • Implemented statedb.admin - 1h
  • Updated docs - 4h
  • Debugging - 3h
  • Recorded worklog - 10min
  • Loggedt tasks - 5min
  • @output:
    • STATE_v0.0.27
    • datashel_PR

---

Worklog

worklog-281

---

Proposals

• Need to use a proxy for tracking override changes for an edge case described in the worklog
• Strict dataset group names will be enforced for quick_editor

[serapath]

feedback 2025.08.26
Cool - pull request merged. Good work.
Now regarding documentation - its a lot. It's okay that LLM helps, but maybe we need to plan an overall high level structure/outline (what sections we want) and then instruct LLM to help section by section, so it is easier to correct the LLM than when it needs to work on a large text all at once.

The goal is to keep things 100% correct and to cover 100% of the API surface to not miss anything, all while keeping it as minimal and concise as possible :-) ...the minimal/concise is often what LLMs struggle with.

---

Regarding overrides tracking

We don't need to track which override introduced which part of the data, all we need to know is which module introduced the particular override that was used in the final running app and which other overrides/fallbacks did it invoke to help produce the finaly initial component module or instance drive state.
I think that is enough for now. ...that should be way less than what you are describing, because for that we need a full "membrane" implementation, which is a lot of work and we will focus on when we get to the "secure sandboxing".

Apart from that, a full membrance solution is quite a bit of a performance penalty and what's the real benefit.

Of course its nice to know everyting down to the atom when you want to track down bugs - but if things are correct - all you get is a significant performance hit for no reason.
So how much tracking is good enough, so that things are still as fast as possible and that you have enough information that you can find the problem if it happens (even if it takes a bit longer than if you tracked every detail) ...it's a tradeoff, but i would say its good enough to track enough so that with a bit more effort we can find things and in return we still have great performance :-)

Finally:
In the specific case, that an override sets a value that is exactly the same as in what is being overriden, then it also does not matter. We can just ignore it an pretend it was not touched, because any bug that would be introduced because of the value that was set is ALSO introduced when it is not set. Once a developer fixes the issue in one place, they are NOT the same anymore and hence will get detected because now they are different i guess?

That said - as said above - i wouldnt even track it to that level of detail at all, but if you feel like implementing the Proxy, make that code a standalone internal module, so we can re-use it or improve it when we work on sandboxing in the future where we will need a membranne

[alyhxn]

Tasks - 2025-09-03

• Update - STATE_v0.0.27
  • Resolved the issue to make dataset creation strict - 4h
  • Add precise $ref change tracking - 3h
  • @outputs 📦
    • STATE_v0.0.28

---

Worklog

worklog-282

[serapath]

feedback 2025.09.04
all feedback on discord this time :-)