refactor(js): unify env lifecycle refcounting

[nazarhussain]

Motivation

export_module.zig (bare atomic) and js/io.zig (mutex-guarded refcount) duplicate the same retain/release lifecycle. That split is the root cause of both open fixes: the cross-env init race (#31) and the missed cleanup on registration failure (#52).

Description

• Add lifecycle.SharedResource(T, hooks): a mutex-guarded refcount that runs fallible init under the lock before incrementing, and cleanup after decrementing.
• Port js/io.zig and the module lifecycle in export_module.zig onto it. No public API changes.

Both fixes hold by construction:

• Hooks are serialized per module, and the refcount only increments after init succeeds — fixes the fix(js): serialize moduleInit/cleanupHook across N-API envs #31 race, with registration kept outside the lock.
• Rollback goes through release(), which always runs cleanup with the correct count — fixes fix(js): roll back module lifecycle initialization #52.

Supersedes #31 and #52.

Testing

New tests in lifecycle.zig cover hook ordering, init-failure rollback, and instance visibility. zig build test: 54/54 pass.

🤖 Generated with Claude Code

[nazarhussain]

@GrapeBaBa The changes in #31 and #52 were using the pattern and logic we already have in io.zig so I extracted it out to a common file lifecycle.zig and used across both io.zig and export_module.zig.

See if that seems good to you.

[spiral-ladder]

a few questions

[spiral-ladder]

should we add a test that exercises the mutex?

[nazarhussain]

Yes added the tests for it.

[spiral-ladder]

im assuming the resource has to be retained for this to be threadsafe?

[nazarhussain]

Yes correct, added to docs.

[GrapeBaBa]

I’m not sure this abstraction is necessary. Different resource types may not share the same lifecycle state machine. If one resource’s lifecycle evolves independently, some transitions or invariants may have to be handled outside SharedResource, splitting a single state machine between the generic helper and its callers. That could make lifecycle correctness harder to reason about.

If we keep this abstraction, I think get() should make its lifetime requirements explicit. It returns *T after releasing the mutex, so SharedResource itself does not guarantee that the instance remains valid during use. Consider returning a lease that holds a retain until released. At minimum, document that the caller must already hold a retain for the entire lifetime of the returned pointer.

[nazarhussain]

The abstraction is deliberately scoped to the one state machine we already have twice: env-scoped refcounted init/teardown. Having it in two copies is what produced #31 and #52.

It's also internal — not exported from js.zig — so if a future resource's lifecycle doesn't fit, it just doesn't use this helper.

On get() agreed the lifetime requirement should be explicit — I've documented that the returned pointer is only valid while the caller holds a retain.

[spiral-ladder]

i also like that this makes the lifecycle concern in zapi rather than consumer

[spiral-ladder]

this generally lgtm, but will wait on @GrapeBaBa for second opinion

[GrapeBaBa]

The SharedResource unit tests cover failures within retain(), but the rollback after a successful retain is orchestrated by exportModule through its errdefer blocks. That behavior therefore seems to need coverage at the exportModule integration boundary rather than in SharedResource.

Could we add tests that inject failures from registerDecls, the custom register hook, and cleanup-hook installation, and verify that the module lifecycle and shared IO retains are each released exactly once?