Zecheng Zhang
98fcdcb2e2
python's GenericResource wires the whole generic command set, the glob resolver and the VFS/FUSE ops from one table, and TypeScript had every ingredient but no class that assembled them, so a custom backend there was still written out by hand. Adds GenericResource<A>, generic over the accessor so the table is checked against the core functions it holds rather than against Accessor. It keeps TypeScript's own wiring style: commands() and ops() return arrays instead of python's register() loop mutating state in the constructor. And there is no sdk.ts, because core's barrel is 99 lines and gated in both directions while the ./* exports map already makes every module importable, so the five names the new example and doc reach for are the only additions to it. Both classes gained sizes_always_known and supports_snapshot. Without the first, no user-written backend could be mounted on FSKit at all, since resolve_backend refuses a resource that cannot size its files. The two one-file examples answer one shared truth file, so the two SDKs cannot drift without a red build. docs/typescript/resource/new.mdx is the twin of the python page, whose stale du_total/du_all is corrected to du. The layout baseline drops to 255: resource/generic was one of the counted divergences.
TypeScript examples
Runnable scripts, one directory per backend or topic. The examples import the
workspace packages from typescript/, so rebuild those dists first:
cd typescript && pnpm --filter @struktoai/mirage-core build && pnpm --filter @struktoai/mirage-node build
cd ../examples/typescript && pnpm install && pnpm exec tsx s3/s3.ts
Naming: <backend>.ts uses the command surface, <backend>_fuse.ts adds a
kernel mount, <backend>_vfs.ts stays fully virtual.
Mount backends: fuse vs fskit
Apple has deprecated third-party kernel extensions; on Apple Silicon the
macFUSE kext already needs a reduced-security boot and admin approval, and
future macOS releases are expected to stop loading it entirely. FSKit
(macOS 15.4+) is Apple's supported userspace replacement, and macFUSE 5.x
serves the same libfuse API through it, so backend: 'fskit' keeps real
mounts working on Macs where the kext is blocked.
flowchart LR
A[cat /Volumes/.../file] --> K[kernel VFS]
K -->|backend=fuse| X[macFUSE kext] --> L[libfuse]
K -->|backend=fskit| F[fskitd + macFUSE FSKit module] --> L
L --> M[MirageFS] --> R[resource]
Same upper half either way; only the kernel-to-userspace hop changes.
Two FUSE rules here: never touch your own mountpoint synchronously (the
mount is served by this process's event loop; probe from a child process,
see fuse/helper.ts), and treat fskit as read-mostly and experimental
(create/mkdir/rename return ENOSYS, and one test run wedged on a
write). fuse/fskit.ts demonstrates it; details in
docs/typescript/setup/fuse.mdx.