Filesystem
Local filesystem store for walkerOS server flows. It reads and writes files relative to a base directory, with path traversal protection.
Installation
npm install @walkeros/server-store-fs- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import { storeFsInit } from '@walkeros/server-store-fs';
await startFlow({
stores: {
assets: {
code: storeFsInit,
config: {
settings: {
basePath: './public',
},
},
},
},
});Add to your flow.json:
"stores": {
"assets": {
"package": "@walkeros/server-store-fs",
"config": {
"settings": {
"basePath": "./public"
}
}
}
}Configuration
This store uses the standard store config wrapper (consent, data, env, id, ...). For the shared fields see store configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
basePath | string | Root directory for file operations. All keys are resolved relative to this path. |
Mapping
This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
Examples
Read file
Read an existing file and receive its raw bytes byte-exact
{
"operation": "get",
"key": "walker.js"
}get("walker.js", "Bytes<console.log(\"walkerOS\")>")Write file
Write creates intermediate directories automatically
{
"operation": "set",
"key": "js/custom/tracker.js",
"value": "Buffer<(function(){...})()>"
}set("js/custom/tracker.js", "Buffer<(function(){...})()>")When it fails
- failed read: The file system fails the read with another error than a missing file (permission denied, a broken disk): get throws a StepError instead of answering a miss. Reported as
failedwith codetransport.
Structured vs file mode
The fs store has two modes, decided once at init by config.file:
- Structured (default): values are structured
StoreValuedata, serialized to and from disk by the shared core codec. Use for session state, lookups, and cached responses. - File (
file: true): values persist as raw bytes byte-exact.set()accepts aUint8Arrayorstringand writes it untouched;get()hands the exact bytes back. Use for serving assets such as walker.js, where byte fidelity matters.
One store instance is exactly one mode. Set file: true on the store declaration to opt into byte-exact serving.
API
const file = await store.get('walker.js'); // StoreValue | undefined
await store.set('data.json', { ok: true }); // structured value
await store.set(
'walker.js',
new Uint8Array([
/*…*/
]),
); // file mode: raw bytes
await store.delete('old-file.txt'); // voidIn file mode, get() returns the bytes as a Uint8Array leaf and set() rejects non-Uint8Array, non-string values with a clear error, so served assets stay intact byte-for-byte.
File serving pattern
Use with the file transformer to serve static assets from the local filesystem. The express source maps the request path into ingest.path and runs the transformer in its next chain; a transformer that no chain names never runs. Set file: true so the store persists and returns bytes byte-exact:
{
"stores": {
"assets": {
"package": "@walkeros/server-store-fs",
"config": {
"settings": { "basePath": "./public" },
"file": true
}
}
},
"sources": {
"http": {
"package": "@walkeros/server-source-express",
"config": {
"settings": { "paths": ["/collect", "/static/*path"] },
"ingest": { "map": { "path": { "key": "path" } } }
},
"next": "file"
}
},
"transformers": {
"file": {
"package": "@walkeros/server-transformer-file",
"config": { "settings": { "prefix": "/static" } },
"env": { "store": "$store.assets" }
}
}
}A GET to /static/walker.js answers with ./public/walker.js from disk; a path the store does not hold gets the source's usual answer (for a GET, the express source's 200 tracking pixel). Omit file (or set it false) for a structured key-value store instead.
A relative basePath resolves against the working directory of the process. The runtime changes into the bundle's folder before it loads the flow, so there ./public is the public folder next to the bundle; copy it there with include, or use an absolute path.
Security
- Path traversal protection: Keys with a
..segment (/or\separated) or a leading/or\are rejected:getanswers a miss,setanddeletedo nothing. Each rejection is a WARN line, which the default log level (ERROR) does not show - Base path scoping: All operations are restricted to the configured
basePathdirectory - Intermediate directories:
set()creates parent directories automatically viamkdir -p
When to use
| Scenario | Recommended store |
|---|---|
| Local development | Filesystem: files on disk, no credentials needed |
| Docker with baked-in assets | Filesystem: mount or copy files into the image |
| Cloud / managed deployments | S3: files in a bucket, hot-swappable |
| Caching / ephemeral data | Built-in cache tier: in-process, no I/O |