@eserstack/cache 0.0.0-stage → 5.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +13 -0
- package/README.md +91 -2
- package/dist/cache.d.ts +52 -0
- package/dist/cache.js +126 -0
- package/dist/ffi-client.d.ts +8 -0
- package/dist/ffi-client.js +9 -0
- package/dist/host.d.ts +44 -0
- package/dist/host.js +78 -0
- package/dist/mod.d.ts +51 -0
- package/dist/mod.js +5 -0
- package/dist/primitives.d.ts +99 -0
- package/dist/primitives.js +2 -0
- package/dist/xdg.d.ts +107 -0
- package/dist/xdg.js +82 -0
- package/package.json +32 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
Copyright 2023-present Eser Ozvataf and other contributors.
|
|
2
|
+
|
|
3
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
you may not use this file except in compliance with the License.
|
|
5
|
+
You may obtain a copy of the License at
|
|
6
|
+
|
|
7
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
|
|
9
|
+
Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
See the License for the specific language governing permissions and
|
|
13
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,3 +1,92 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 📦 [@eserstack/cache](./)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Note:** JSR is frozen at 4.5.x. From 5.0.0, `@eserstack/cache` is published
|
|
4
|
+
> on npm under the same name (`pnpm add @eserstack/cache`); the JSR versions
|
|
5
|
+
> stay available but get no updates.
|
|
6
|
+
|
|
7
|
+
> **eserstack Library** — [eser/stack on GitHub](https://github.com/eser/stack)
|
|
8
|
+
> **Install:** `pnpm add @eserstack/cache`
|
|
9
|
+
|
|
10
|
+
Cross-platform cache management with XDG-compliant directory structure.
|
|
11
|
+
|
|
12
|
+
## Features
|
|
13
|
+
|
|
14
|
+
- **XDG Compliance**: Follows XDG Base Directory Specification on Linux
|
|
15
|
+
- **Cross-Platform**: Platform-specific paths for macOS and Windows
|
|
16
|
+
- **Versioned Caching**: Built-in support for version-based cache isolation
|
|
17
|
+
- **Simple API**: Create, check, list, and clear cached items
|
|
18
|
+
|
|
19
|
+
## Quick Start
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
import * as cache from "@eserstack/cache";
|
|
23
|
+
|
|
24
|
+
// Create a cache manager for your application
|
|
25
|
+
const manager = cache.createCacheManager({
|
|
26
|
+
app: { name: "my-cli", org: "eser" },
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
// Get versioned cache path
|
|
30
|
+
const binaryPath = manager.getVersionedPath("1.0.0", "binary");
|
|
31
|
+
// Linux: ~/.cache/eser/my-cli/v1.0.0/binary
|
|
32
|
+
// macOS: ~/Library/Caches/eser/my-cli/v1.0.0/binary
|
|
33
|
+
// Windows: %LOCALAPPDATA%/eser/my-cli/v1.0.0/binary
|
|
34
|
+
|
|
35
|
+
// Check if cached item exists
|
|
36
|
+
if (await manager.exists(binaryPath)) {
|
|
37
|
+
console.log("Using cached binary");
|
|
38
|
+
} else {
|
|
39
|
+
await manager.ensureDir(manager.getCacheDir());
|
|
40
|
+
// Download and cache...
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
// List cached items
|
|
44
|
+
const entries = await manager.list();
|
|
45
|
+
|
|
46
|
+
// Clear cache
|
|
47
|
+
await manager.clear();
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## XDG Directory Access
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
import * as cache from "@eserstack/cache";
|
|
54
|
+
|
|
55
|
+
const cacheHome = cache.getXdgCacheHome(); // ~/.cache or ~/Library/Caches
|
|
56
|
+
const dataHome = cache.getXdgDataHome(); // ~/.local/share or ~/Library/Application Support
|
|
57
|
+
const configHome = cache.getXdgConfigHome(); // ~/.config or ~/Library/Preferences
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## API Reference
|
|
61
|
+
|
|
62
|
+
### `createCacheManager(options)`
|
|
63
|
+
|
|
64
|
+
Creates a cache manager instance.
|
|
65
|
+
|
|
66
|
+
- `options.app.name` - Application name
|
|
67
|
+
- `options.app.org` - Organization name (optional)
|
|
68
|
+
- `options.baseDir` - Custom base directory (optional)
|
|
69
|
+
|
|
70
|
+
### CacheManager Methods
|
|
71
|
+
|
|
72
|
+
| Method | Description |
|
|
73
|
+
| --------------------------------- | ------------------------------------ |
|
|
74
|
+
| `getCacheDir()` | Get the base cache directory path |
|
|
75
|
+
| `getVersionedPath(version, name)` | Get a versioned cache path |
|
|
76
|
+
| `exists(path)` | Check if a path exists |
|
|
77
|
+
| `ensureDir(path)` | Create directory if it doesn't exist |
|
|
78
|
+
| `list()` | List all cache entries |
|
|
79
|
+
| `remove(path)` | Remove a cached item |
|
|
80
|
+
| `clear()` | Clear the entire cache |
|
|
81
|
+
|
|
82
|
+
Every method and the XDG functions run in Go through the `@eserstack/ajan`
|
|
83
|
+
bridge (the native library, or its WASM build). The synchronous ones load the
|
|
84
|
+
bridge on first use, and its WASM build compiles on the calling thread. When
|
|
85
|
+
neither loads, they throw, and the async methods reject, with the bridge's load
|
|
86
|
+
error. `exists()`, `ensureDir()` and `remove()` take a path relative to the
|
|
87
|
+
cache directory or an absolute path.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
🔗 For further details, visit the
|
|
92
|
+
[eserstack repository](https://github.com/eser/stack).
|
package/dist/cache.d.ts
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cache manager implementation.
|
|
3
|
+
*
|
|
4
|
+
* Provides versioned cache storage with XDG-compliant directory structure.
|
|
5
|
+
* Delegates the path resolution and the filesystem operations to Go
|
|
6
|
+
* (`pkg/ajan/cachefx`) through the `@eserstack/ajan` bridge; without the
|
|
7
|
+
* bridge they throw or reject with its load error.
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```typescript
|
|
11
|
+
* import * as cache from "@eserstack/cache";
|
|
12
|
+
* import { runtime } from "@eserstack/standards/cross-runtime";
|
|
13
|
+
*
|
|
14
|
+
* const manager = cache.createCacheManager({
|
|
15
|
+
* app: { name: "my-cli", org: "eser" }
|
|
16
|
+
* });
|
|
17
|
+
*
|
|
18
|
+
* // Get versioned cache path
|
|
19
|
+
* const binaryPath = manager.getVersionedPath("1.0.0", "binary");
|
|
20
|
+
*
|
|
21
|
+
* // Ensure directory exists
|
|
22
|
+
* await manager.ensureDir(runtime.path.dirname(binaryPath));
|
|
23
|
+
*
|
|
24
|
+
* // Check if cached
|
|
25
|
+
* if (await manager.exists(binaryPath)) {
|
|
26
|
+
* console.log("Using cached binary");
|
|
27
|
+
* }
|
|
28
|
+
* ```
|
|
29
|
+
*
|
|
30
|
+
* @module
|
|
31
|
+
*/
|
|
32
|
+
import type { CacheManager, CacheManagerOptions } from "./primitives.ts";
|
|
33
|
+
/**
|
|
34
|
+
* Creates a cache manager for the specified application.
|
|
35
|
+
*
|
|
36
|
+
* @param options - Cache manager configuration
|
|
37
|
+
* @returns A CacheManager instance
|
|
38
|
+
*
|
|
39
|
+
* @example
|
|
40
|
+
* ```typescript
|
|
41
|
+
* import * as cache from "@eserstack/cache";
|
|
42
|
+
*
|
|
43
|
+
* const manager = cache.createCacheManager({
|
|
44
|
+
* app: { name: "my-cli", org: "eser" }
|
|
45
|
+
* });
|
|
46
|
+
*
|
|
47
|
+
* const path = manager.getVersionedPath("1.0.0", "binary");
|
|
48
|
+
* // On Linux: ~/.cache/eser/my-cli/v1.0.0/binary
|
|
49
|
+
* // On macOS: ~/Library/Caches/eser/my-cli/v1.0.0/binary
|
|
50
|
+
* ```
|
|
51
|
+
*/
|
|
52
|
+
export declare const createCacheManager: (options: CacheManagerOptions) => CacheManager;
|
package/dist/cache.js
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
import * as ffiClient from "./ffi-client.js";
|
|
3
|
+
import * as host from "./host.js";
|
|
4
|
+
/**
|
|
5
|
+
* Creates a cache manager for the specified application.
|
|
6
|
+
*
|
|
7
|
+
* @param options - Cache manager configuration
|
|
8
|
+
* @returns A CacheManager instance
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* ```typescript
|
|
12
|
+
* import * as cache from "@eserstack/cache";
|
|
13
|
+
*
|
|
14
|
+
* const manager = cache.createCacheManager({
|
|
15
|
+
* app: { name: "my-cli", org: "eser" }
|
|
16
|
+
* });
|
|
17
|
+
*
|
|
18
|
+
* const path = manager.getVersionedPath("1.0.0", "binary");
|
|
19
|
+
* // On Linux: ~/.cache/eser/my-cli/v1.0.0/binary
|
|
20
|
+
* // On macOS: ~/Library/Caches/eser/my-cli/v1.0.0/binary
|
|
21
|
+
* ```
|
|
22
|
+
*/
|
|
23
|
+
export const createCacheManager = (options) => {
|
|
24
|
+
const { app, baseDir } = options;
|
|
25
|
+
// Go handle for this cache instance (created lazily on first async operation).
|
|
26
|
+
let _handlePromise = null;
|
|
27
|
+
const getHandle = () => {
|
|
28
|
+
if (_handlePromise === null) {
|
|
29
|
+
_handlePromise = ffiClient.requireLib().then((lib) => {
|
|
30
|
+
const result = lib.call("cacheCreate", {
|
|
31
|
+
app: { name: app.name, org: app.org },
|
|
32
|
+
baseDir,
|
|
33
|
+
host: host.currentHost(),
|
|
34
|
+
});
|
|
35
|
+
if (result.error) {
|
|
36
|
+
throw new Error(result.error);
|
|
37
|
+
}
|
|
38
|
+
return result.handle ?? "";
|
|
39
|
+
});
|
|
40
|
+
}
|
|
41
|
+
return _handlePromise;
|
|
42
|
+
};
|
|
43
|
+
// Sync methods: Go resolves the paths through the bridge, which loads
|
|
44
|
+
// synchronously on first use.
|
|
45
|
+
const getCacheDir = () => host.resolveAppPaths({ app, baseDir }).appDir;
|
|
46
|
+
const getVersionedPath = (version, name) => host.resolveAppPaths({ app, baseDir, version, item: name }).versionedPath;
|
|
47
|
+
// Go resolves a relative path against the cache directory.
|
|
48
|
+
const exists = async (path) => {
|
|
49
|
+
const handle = await getHandle();
|
|
50
|
+
const lib = ffiClient.getLib();
|
|
51
|
+
const result = lib.call("cacheExists", { handle, path });
|
|
52
|
+
if (result.error) {
|
|
53
|
+
throw new Error(result.error);
|
|
54
|
+
}
|
|
55
|
+
return result.exists === true;
|
|
56
|
+
};
|
|
57
|
+
const ensureDir = async (path) => {
|
|
58
|
+
const handle = await getHandle();
|
|
59
|
+
const lib = ffiClient.getLib();
|
|
60
|
+
const result = lib.call("cacheEnsureDir", { handle, path });
|
|
61
|
+
if (result.error) {
|
|
62
|
+
throw new Error(result.error);
|
|
63
|
+
}
|
|
64
|
+
};
|
|
65
|
+
const list = async () => {
|
|
66
|
+
const handle = await getHandle();
|
|
67
|
+
const lib = ffiClient.getLib();
|
|
68
|
+
const result = lib.call("cacheList", { handle });
|
|
69
|
+
if (result.error) {
|
|
70
|
+
throw new Error(result.error);
|
|
71
|
+
}
|
|
72
|
+
return (result.entries ?? []).map((e) => ({
|
|
73
|
+
path: e.path,
|
|
74
|
+
name: e.name,
|
|
75
|
+
isDirectory: e.isDirectory,
|
|
76
|
+
size: e.size,
|
|
77
|
+
mtime: e.mtimeUnix ? new Date(e.mtimeUnix * 1000) : null,
|
|
78
|
+
}));
|
|
79
|
+
};
|
|
80
|
+
const remove = async (path) => {
|
|
81
|
+
const handle = await getHandle();
|
|
82
|
+
const lib = ffiClient.getLib();
|
|
83
|
+
const result = lib.call("cacheRemove", { handle, path });
|
|
84
|
+
if (result.error) {
|
|
85
|
+
throw new Error(result.error);
|
|
86
|
+
}
|
|
87
|
+
};
|
|
88
|
+
const clear = async () => {
|
|
89
|
+
const handle = await getHandle();
|
|
90
|
+
const lib = ffiClient.getLib();
|
|
91
|
+
const result = lib.call("cacheClear", { handle });
|
|
92
|
+
if (result.error) {
|
|
93
|
+
throw new Error(result.error);
|
|
94
|
+
}
|
|
95
|
+
};
|
|
96
|
+
// Reset _handlePromise to null BEFORE calling Go so a concurrent second close
|
|
97
|
+
// sees null and returns early rather than closing an already-freed handle.
|
|
98
|
+
const close = async () => {
|
|
99
|
+
if (_handlePromise === null)
|
|
100
|
+
return;
|
|
101
|
+
let handle;
|
|
102
|
+
try {
|
|
103
|
+
handle = await _handlePromise;
|
|
104
|
+
}
|
|
105
|
+
catch {
|
|
106
|
+
_handlePromise = null;
|
|
107
|
+
return;
|
|
108
|
+
}
|
|
109
|
+
_handlePromise = null;
|
|
110
|
+
const lib = ffiClient.getLib();
|
|
111
|
+
if (lib !== null) {
|
|
112
|
+
lib.call("cacheClose", { handle });
|
|
113
|
+
}
|
|
114
|
+
};
|
|
115
|
+
return {
|
|
116
|
+
getCacheDir,
|
|
117
|
+
getVersionedPath,
|
|
118
|
+
exists,
|
|
119
|
+
ensureDir,
|
|
120
|
+
list,
|
|
121
|
+
remove,
|
|
122
|
+
clear,
|
|
123
|
+
close,
|
|
124
|
+
[Symbol.asyncDispose]: close,
|
|
125
|
+
};
|
|
126
|
+
};
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* This package's view of the Go bridge.
|
|
3
|
+
*
|
|
4
|
+
* The loader itself lives in `@eserstack/ajan/ffi/client` and is shared with
|
|
5
|
+
* every other package, so the whole process opens the library once. This module
|
|
6
|
+
* stays as the import path the package's own code already uses.
|
|
7
|
+
*/
|
|
8
|
+
export { ensureLib, getLib, getLoadError, requireLib, requireLibSync, } from "@eserstack/ajan/ffi/client";
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* This package's view of the Go bridge.
|
|
4
|
+
*
|
|
5
|
+
* The loader itself lives in `@eserstack/ajan/ffi/client` and is shared with
|
|
6
|
+
* every other package, so the whole process opens the library once. This module
|
|
7
|
+
* stays as the import path the package's own code already uses.
|
|
8
|
+
*/
|
|
9
|
+
export { ensureLib, getLib, getLoadError, requireLib, requireLibSync, } from "@eserstack/ajan/ffi/client";
|
package/dist/host.d.ts
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { AppIdentifier } from "./primitives.ts";
|
|
2
|
+
/** The `host` field of the cache bridge requests. */
|
|
3
|
+
export interface HostFacts {
|
|
4
|
+
readonly platform: string;
|
|
5
|
+
readonly home: string;
|
|
6
|
+
readonly env: Readonly<Record<string, string>>;
|
|
7
|
+
}
|
|
8
|
+
/** Reads the host facts of this process. */
|
|
9
|
+
export declare const currentHost: () => HostFacts;
|
|
10
|
+
/** What {@link resolvePaths} asks Go for beyond the base directories. */
|
|
11
|
+
export interface ResolvePathsRequest {
|
|
12
|
+
readonly app?: AppIdentifier;
|
|
13
|
+
readonly baseDir?: string;
|
|
14
|
+
readonly version?: string;
|
|
15
|
+
readonly item?: string;
|
|
16
|
+
}
|
|
17
|
+
/** The base directories and, for a request with an app, its paths. */
|
|
18
|
+
export interface ResolvedPaths {
|
|
19
|
+
readonly cacheHome: string;
|
|
20
|
+
readonly dataHome: string;
|
|
21
|
+
readonly configHome: string;
|
|
22
|
+
readonly appDir?: string;
|
|
23
|
+
readonly versionedPath?: string;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Resolves the paths of `request` in Go (`cacheResolvePaths`), synchronously.
|
|
27
|
+
* The bridge loads on first use.
|
|
28
|
+
*
|
|
29
|
+
* @throws {Error} When the bridge is unavailable (its load error is the
|
|
30
|
+
* `cause`), or Go answers an error.
|
|
31
|
+
*/
|
|
32
|
+
export declare const resolvePaths: (request: ResolvePathsRequest) => ResolvedPaths;
|
|
33
|
+
/**
|
|
34
|
+
* The app paths of `request`, which names an app.
|
|
35
|
+
*
|
|
36
|
+
* @throws {Error} As {@link resolvePaths}, and when the app has no name: Go
|
|
37
|
+
* answers no app paths then, as `cacheCreate` refuses one.
|
|
38
|
+
*/
|
|
39
|
+
export declare const resolveAppPaths: (request: ResolvePathsRequest & {
|
|
40
|
+
readonly app: AppIdentifier;
|
|
41
|
+
}) => {
|
|
42
|
+
readonly appDir: string;
|
|
43
|
+
readonly versionedPath: string;
|
|
44
|
+
};
|
package/dist/host.js
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
/**
|
|
3
|
+
* The host facts the Go side resolves the base directories from, and the
|
|
4
|
+
* synchronous path resolution over them.
|
|
5
|
+
*
|
|
6
|
+
* The WASM build of the bridge runs as wasip1, without the host's platform,
|
|
7
|
+
* home directory or environment, so every request that resolves a directory
|
|
8
|
+
* carries them. Go owns the rules (`pkg/ajan/cachefx`); this module only reads
|
|
9
|
+
* the values and sends them. Not exported from the package.
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import * as standardsCrossRuntime from "@eserstack/standards/cross-runtime";
|
|
14
|
+
import * as ffiClient from "./ffi-client.js";
|
|
15
|
+
const runtime = standardsCrossRuntime.runtime;
|
|
16
|
+
/** The environment variables the base directory rules of cachefx read. */
|
|
17
|
+
const HOST_ENV_NAMES = [
|
|
18
|
+
"XDG_CACHE_HOME",
|
|
19
|
+
"XDG_DATA_HOME",
|
|
20
|
+
"XDG_CONFIG_HOME",
|
|
21
|
+
"LOCALAPPDATA",
|
|
22
|
+
"APPDATA",
|
|
23
|
+
];
|
|
24
|
+
/** Reads the host facts of this process. */
|
|
25
|
+
export const currentHost = () => {
|
|
26
|
+
const env = {};
|
|
27
|
+
for (const name of HOST_ENV_NAMES) {
|
|
28
|
+
const value = runtime.env.get(name);
|
|
29
|
+
if (value !== undefined) {
|
|
30
|
+
env[name] = value;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
return {
|
|
34
|
+
platform: standardsCrossRuntime.getPlatform(),
|
|
35
|
+
home: standardsCrossRuntime.getHomedir(),
|
|
36
|
+
env,
|
|
37
|
+
};
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* Resolves the paths of `request` in Go (`cacheResolvePaths`), synchronously.
|
|
41
|
+
* The bridge loads on first use.
|
|
42
|
+
*
|
|
43
|
+
* @throws {Error} When the bridge is unavailable (its load error is the
|
|
44
|
+
* `cause`), or Go answers an error.
|
|
45
|
+
*/
|
|
46
|
+
export const resolvePaths = (request) => {
|
|
47
|
+
const { app, baseDir, version, item } = request;
|
|
48
|
+
const answer = ffiClient.requireLibSync().call("cacheResolvePaths", {
|
|
49
|
+
host: currentHost(),
|
|
50
|
+
app: app === undefined ? undefined : { name: app.name, org: app.org },
|
|
51
|
+
baseDir,
|
|
52
|
+
version,
|
|
53
|
+
item,
|
|
54
|
+
});
|
|
55
|
+
if (answer.error !== undefined && answer.error !== "") {
|
|
56
|
+
throw new Error(answer.error);
|
|
57
|
+
}
|
|
58
|
+
return {
|
|
59
|
+
cacheHome: answer.cacheHome ?? "",
|
|
60
|
+
dataHome: answer.dataHome ?? "",
|
|
61
|
+
configHome: answer.configHome ?? "",
|
|
62
|
+
appDir: answer.appDir,
|
|
63
|
+
versionedPath: answer.versionedPath,
|
|
64
|
+
};
|
|
65
|
+
};
|
|
66
|
+
/**
|
|
67
|
+
* The app paths of `request`, which names an app.
|
|
68
|
+
*
|
|
69
|
+
* @throws {Error} As {@link resolvePaths}, and when the app has no name: Go
|
|
70
|
+
* answers no app paths then, as `cacheCreate` refuses one.
|
|
71
|
+
*/
|
|
72
|
+
export const resolveAppPaths = (request) => {
|
|
73
|
+
const { appDir, versionedPath } = resolvePaths(request);
|
|
74
|
+
if (appDir === undefined || versionedPath === undefined) {
|
|
75
|
+
throw new Error("app.name is required");
|
|
76
|
+
}
|
|
77
|
+
return { appDir, versionedPath };
|
|
78
|
+
};
|
package/dist/mod.d.ts
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cache management utilities with XDG-compliant directory structure.
|
|
3
|
+
*
|
|
4
|
+
* Provides cross-platform cache storage that follows:
|
|
5
|
+
* - XDG Base Directory Specification on Linux
|
|
6
|
+
* - Platform conventions on macOS (`~/Library/Caches`)
|
|
7
|
+
* - Platform conventions on Windows (`%LOCALAPPDATA%`)
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```typescript
|
|
11
|
+
* import * as cache from "@eserstack/cache";
|
|
12
|
+
* import { runtime } from "@eserstack/standards/cross-runtime";
|
|
13
|
+
*
|
|
14
|
+
* // Create a cache manager for your application
|
|
15
|
+
* const manager = cache.createCacheManager({
|
|
16
|
+
* app: { name: "my-cli", org: "eser" }
|
|
17
|
+
* });
|
|
18
|
+
*
|
|
19
|
+
* // Get versioned cache path
|
|
20
|
+
* const binaryPath = manager.getVersionedPath("1.0.0", "binary");
|
|
21
|
+
*
|
|
22
|
+
* // Check if cached item exists
|
|
23
|
+
* if (await manager.exists(binaryPath)) {
|
|
24
|
+
* console.log("Using cached binary");
|
|
25
|
+
* } else {
|
|
26
|
+
* await manager.ensureDir(runtime.path.dirname(binaryPath));
|
|
27
|
+
* // Download and cache...
|
|
28
|
+
* }
|
|
29
|
+
*
|
|
30
|
+
* // List cached items
|
|
31
|
+
* const entries = await manager.list();
|
|
32
|
+
*
|
|
33
|
+
* // Clear cache
|
|
34
|
+
* await manager.clear();
|
|
35
|
+
* ```
|
|
36
|
+
*
|
|
37
|
+
* @example
|
|
38
|
+
* ```typescript
|
|
39
|
+
* // Direct XDG directory access
|
|
40
|
+
* import * as cache from "@eserstack/cache";
|
|
41
|
+
*
|
|
42
|
+
* const cacheHome = cache.getXdgCacheHome();
|
|
43
|
+
* const dataHome = cache.getXdgDataHome();
|
|
44
|
+
* const configHome = cache.getXdgConfigHome();
|
|
45
|
+
* ```
|
|
46
|
+
*
|
|
47
|
+
* @module
|
|
48
|
+
*/
|
|
49
|
+
export type { AppIdentifier, CacheEntry, CacheManager, CacheManagerOptions, } from "./primitives.ts";
|
|
50
|
+
export { createCacheManager } from "./cache.ts";
|
|
51
|
+
export { getAppCacheDir, getVersionedCachePath, getXdgCacheHome, getXdgConfigHome, getXdgDataHome, } from "./xdg.ts";
|
package/dist/mod.js
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
// Re-export cache manager factory
|
|
3
|
+
export { createCacheManager } from "./cache.js";
|
|
4
|
+
// Re-export XDG utilities
|
|
5
|
+
export { getAppCacheDir, getVersionedCachePath, getXdgCacheHome, getXdgConfigHome, getXdgDataHome, } from "./xdg.js";
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Type definitions for cache management.
|
|
3
|
+
*
|
|
4
|
+
* @module
|
|
5
|
+
*/
|
|
6
|
+
/**
|
|
7
|
+
* Application identifier for cache directories.
|
|
8
|
+
*/
|
|
9
|
+
export interface AppIdentifier {
|
|
10
|
+
/** Application name (e.g., "my-cli") */
|
|
11
|
+
readonly name: string;
|
|
12
|
+
/** Organization name (optional, e.g., "eser") */
|
|
13
|
+
readonly org?: string;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Options for creating a cache manager.
|
|
17
|
+
*/
|
|
18
|
+
export interface CacheManagerOptions {
|
|
19
|
+
/** Application identifier */
|
|
20
|
+
readonly app: AppIdentifier;
|
|
21
|
+
/** Custom base cache directory (overrides XDG default) */
|
|
22
|
+
readonly baseDir?: string;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Information about a cached entry.
|
|
26
|
+
*/
|
|
27
|
+
export interface CacheEntry {
|
|
28
|
+
/** Entry path relative to cache root */
|
|
29
|
+
readonly path: string;
|
|
30
|
+
/** Entry name (filename or directory name) */
|
|
31
|
+
readonly name: string;
|
|
32
|
+
/** Whether this is a directory */
|
|
33
|
+
readonly isDirectory: boolean;
|
|
34
|
+
/** File size in bytes (0 for directories) */
|
|
35
|
+
readonly size: number;
|
|
36
|
+
/** Last modification time */
|
|
37
|
+
readonly mtime: Date | null;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Cache manager interface for managing versioned cache storage.
|
|
41
|
+
*/
|
|
42
|
+
export interface CacheManager {
|
|
43
|
+
/**
|
|
44
|
+
* Gets the base cache directory for this application.
|
|
45
|
+
*
|
|
46
|
+
* @returns Absolute path to the cache directory
|
|
47
|
+
*/
|
|
48
|
+
getCacheDir(): string;
|
|
49
|
+
/**
|
|
50
|
+
* Gets a versioned path within the cache.
|
|
51
|
+
* The version is normalized to always include 'v' prefix.
|
|
52
|
+
*
|
|
53
|
+
* @param version - Version string (e.g., "1.0.0" or "v1.0.0")
|
|
54
|
+
* @param name - Name of the cached item
|
|
55
|
+
* @returns Absolute path to the versioned cache location
|
|
56
|
+
*
|
|
57
|
+
* @example
|
|
58
|
+
* ```typescript
|
|
59
|
+
* const path = cache.getVersionedPath("1.0.0", "binary");
|
|
60
|
+
* // Returns: ~/.cache/myapp/v1.0.0/binary
|
|
61
|
+
* ```
|
|
62
|
+
*/
|
|
63
|
+
getVersionedPath(version: string, name: string): string;
|
|
64
|
+
/**
|
|
65
|
+
* Checks if a path exists in the cache.
|
|
66
|
+
*
|
|
67
|
+
* @param path - Path to check (relative or absolute)
|
|
68
|
+
* @returns True if the path exists
|
|
69
|
+
*/
|
|
70
|
+
exists(path: string): Promise<boolean>;
|
|
71
|
+
/**
|
|
72
|
+
* Ensures a directory exists, creating it if necessary.
|
|
73
|
+
*
|
|
74
|
+
* @param path - Directory path to ensure exists
|
|
75
|
+
*/
|
|
76
|
+
ensureDir(path: string): Promise<void>;
|
|
77
|
+
/**
|
|
78
|
+
* Lists all entries in the cache directory.
|
|
79
|
+
*
|
|
80
|
+
* @returns Array of cache entries
|
|
81
|
+
*/
|
|
82
|
+
list(): Promise<CacheEntry[]>;
|
|
83
|
+
/**
|
|
84
|
+
* Removes a path from the cache.
|
|
85
|
+
*
|
|
86
|
+
* @param path - Path to remove
|
|
87
|
+
*/
|
|
88
|
+
remove(path: string): Promise<void>;
|
|
89
|
+
/**
|
|
90
|
+
* Clears the entire cache directory.
|
|
91
|
+
*/
|
|
92
|
+
clear(): Promise<void>;
|
|
93
|
+
/**
|
|
94
|
+
* Releases the Go-side cache handle. Idempotent — safe to call multiple times.
|
|
95
|
+
*/
|
|
96
|
+
close(): Promise<void>;
|
|
97
|
+
/** Explicit resource management support (`await using cache = ...`). */
|
|
98
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
99
|
+
}
|
package/dist/xdg.d.ts
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* XDG Base Directory Specification utilities.
|
|
3
|
+
*
|
|
4
|
+
* Provides cross-platform directory resolution following XDG conventions on Linux
|
|
5
|
+
* and platform-specific conventions on macOS and Windows.
|
|
6
|
+
*
|
|
7
|
+
* Go owns the rules (`pkg/ajan/cachefx`): every function asks it through the
|
|
8
|
+
* `@eserstack/ajan` bridge, which loads synchronously on first use, and throws
|
|
9
|
+
* the bridge's load error when neither the native library nor its WASM build
|
|
10
|
+
* loads.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```typescript
|
|
14
|
+
* import * as xdg from "@eserstack/cache/xdg";
|
|
15
|
+
*
|
|
16
|
+
* // Get base directories
|
|
17
|
+
* const cacheHome = xdg.getXdgCacheHome();
|
|
18
|
+
* const dataHome = xdg.getXdgDataHome();
|
|
19
|
+
* const configHome = xdg.getXdgConfigHome();
|
|
20
|
+
*
|
|
21
|
+
* // Get app-specific cache directory
|
|
22
|
+
* const appCache = xdg.getAppCacheDir({ name: "my-cli", org: "eser" });
|
|
23
|
+
* ```
|
|
24
|
+
*
|
|
25
|
+
* @module
|
|
26
|
+
*/
|
|
27
|
+
import type { AppIdentifier } from "./primitives.ts";
|
|
28
|
+
/**
|
|
29
|
+
* Gets the XDG cache home directory.
|
|
30
|
+
*
|
|
31
|
+
* Resolution order:
|
|
32
|
+
* - Linux: `$XDG_CACHE_HOME` or `~/.cache`
|
|
33
|
+
* - macOS: `~/Library/Caches`
|
|
34
|
+
* - Windows: `%LOCALAPPDATA%` or `~/AppData/Local`
|
|
35
|
+
*
|
|
36
|
+
* @returns Absolute path to cache home directory
|
|
37
|
+
* @throws {Error} When the bridge does not load (its load error is the `cause`)
|
|
38
|
+
*/
|
|
39
|
+
export declare const getXdgCacheHome: () => string;
|
|
40
|
+
/**
|
|
41
|
+
* Gets the XDG data home directory.
|
|
42
|
+
*
|
|
43
|
+
* Resolution order:
|
|
44
|
+
* - Linux: `$XDG_DATA_HOME` or `~/.local/share`
|
|
45
|
+
* - macOS: `~/Library/Application Support`
|
|
46
|
+
* - Windows: `%LOCALAPPDATA%` or `~/AppData/Local`
|
|
47
|
+
*
|
|
48
|
+
* @returns Absolute path to data home directory
|
|
49
|
+
* @throws {Error} When the bridge does not load (its load error is the `cause`)
|
|
50
|
+
*/
|
|
51
|
+
export declare const getXdgDataHome: () => string;
|
|
52
|
+
/**
|
|
53
|
+
* Gets the XDG config home directory.
|
|
54
|
+
*
|
|
55
|
+
* Resolution order:
|
|
56
|
+
* - Linux: `$XDG_CONFIG_HOME` or `~/.config`
|
|
57
|
+
* - macOS: `~/Library/Preferences`
|
|
58
|
+
* - Windows: `%APPDATA%` or `~/AppData/Roaming`
|
|
59
|
+
*
|
|
60
|
+
* @returns Absolute path to config home directory
|
|
61
|
+
* @throws {Error} When the bridge does not load (its load error is the `cause`)
|
|
62
|
+
*/
|
|
63
|
+
export declare const getXdgConfigHome: () => string;
|
|
64
|
+
/**
|
|
65
|
+
* Gets the application-specific cache directory.
|
|
66
|
+
*
|
|
67
|
+
* The directory structure depends on whether an organization is specified:
|
|
68
|
+
* - With org: `{cache_home}/{org}/{name}`
|
|
69
|
+
* - Without org: `{cache_home}/{name}`
|
|
70
|
+
*
|
|
71
|
+
* @param app - Application identifier
|
|
72
|
+
* @returns Absolute path to application cache directory
|
|
73
|
+
* @throws {Error} When the bridge does not load (its load error is the `cause`)
|
|
74
|
+
*
|
|
75
|
+
* @example
|
|
76
|
+
* ```typescript
|
|
77
|
+
* // With organization
|
|
78
|
+
* getAppCacheDir({ name: "my-cli", org: "eser" });
|
|
79
|
+
* // => ~/.cache/eser/my-cli
|
|
80
|
+
*
|
|
81
|
+
* // Without organization
|
|
82
|
+
* getAppCacheDir({ name: "my-cli" });
|
|
83
|
+
* // => ~/.cache/my-cli
|
|
84
|
+
* ```
|
|
85
|
+
*/
|
|
86
|
+
export declare const getAppCacheDir: (app: AppIdentifier) => string;
|
|
87
|
+
/**
|
|
88
|
+
* Gets a versioned path within the application cache.
|
|
89
|
+
*
|
|
90
|
+
* The version is normalized to always include a 'v' prefix for consistency.
|
|
91
|
+
*
|
|
92
|
+
* @param app - Application identifier
|
|
93
|
+
* @param version - Version string (e.g., "1.0.0" or "v1.0.0")
|
|
94
|
+
* @param name - Name of the cached item
|
|
95
|
+
* @returns Absolute path to the versioned cache location
|
|
96
|
+
* @throws {Error} When the bridge does not load (its load error is the `cause`)
|
|
97
|
+
*
|
|
98
|
+
* @example
|
|
99
|
+
* ```typescript
|
|
100
|
+
* getVersionedCachePath({ name: "my-cli" }, "1.0.0", "binary");
|
|
101
|
+
* // => ~/.cache/my-cli/v1.0.0/binary
|
|
102
|
+
*
|
|
103
|
+
* getVersionedCachePath({ name: "my-cli" }, "v2.0.0", "data.json");
|
|
104
|
+
* // => ~/.cache/my-cli/v2.0.0/data.json
|
|
105
|
+
* ```
|
|
106
|
+
*/
|
|
107
|
+
export declare const getVersionedCachePath: (app: AppIdentifier, version: string, name: string) => string;
|
package/dist/xdg.js
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
|
|
2
|
+
import * as host from "./host.js";
|
|
3
|
+
/**
|
|
4
|
+
* Gets the XDG cache home directory.
|
|
5
|
+
*
|
|
6
|
+
* Resolution order:
|
|
7
|
+
* - Linux: `$XDG_CACHE_HOME` or `~/.cache`
|
|
8
|
+
* - macOS: `~/Library/Caches`
|
|
9
|
+
* - Windows: `%LOCALAPPDATA%` or `~/AppData/Local`
|
|
10
|
+
*
|
|
11
|
+
* @returns Absolute path to cache home directory
|
|
12
|
+
* @throws {Error} When the bridge does not load (its load error is the `cause`)
|
|
13
|
+
*/
|
|
14
|
+
export const getXdgCacheHome = () => host.resolvePaths({}).cacheHome;
|
|
15
|
+
/**
|
|
16
|
+
* Gets the XDG data home directory.
|
|
17
|
+
*
|
|
18
|
+
* Resolution order:
|
|
19
|
+
* - Linux: `$XDG_DATA_HOME` or `~/.local/share`
|
|
20
|
+
* - macOS: `~/Library/Application Support`
|
|
21
|
+
* - Windows: `%LOCALAPPDATA%` or `~/AppData/Local`
|
|
22
|
+
*
|
|
23
|
+
* @returns Absolute path to data home directory
|
|
24
|
+
* @throws {Error} When the bridge does not load (its load error is the `cause`)
|
|
25
|
+
*/
|
|
26
|
+
export const getXdgDataHome = () => host.resolvePaths({}).dataHome;
|
|
27
|
+
/**
|
|
28
|
+
* Gets the XDG config home directory.
|
|
29
|
+
*
|
|
30
|
+
* Resolution order:
|
|
31
|
+
* - Linux: `$XDG_CONFIG_HOME` or `~/.config`
|
|
32
|
+
* - macOS: `~/Library/Preferences`
|
|
33
|
+
* - Windows: `%APPDATA%` or `~/AppData/Roaming`
|
|
34
|
+
*
|
|
35
|
+
* @returns Absolute path to config home directory
|
|
36
|
+
* @throws {Error} When the bridge does not load (its load error is the `cause`)
|
|
37
|
+
*/
|
|
38
|
+
export const getXdgConfigHome = () => host.resolvePaths({}).configHome;
|
|
39
|
+
/**
|
|
40
|
+
* Gets the application-specific cache directory.
|
|
41
|
+
*
|
|
42
|
+
* The directory structure depends on whether an organization is specified:
|
|
43
|
+
* - With org: `{cache_home}/{org}/{name}`
|
|
44
|
+
* - Without org: `{cache_home}/{name}`
|
|
45
|
+
*
|
|
46
|
+
* @param app - Application identifier
|
|
47
|
+
* @returns Absolute path to application cache directory
|
|
48
|
+
* @throws {Error} When the bridge does not load (its load error is the `cause`)
|
|
49
|
+
*
|
|
50
|
+
* @example
|
|
51
|
+
* ```typescript
|
|
52
|
+
* // With organization
|
|
53
|
+
* getAppCacheDir({ name: "my-cli", org: "eser" });
|
|
54
|
+
* // => ~/.cache/eser/my-cli
|
|
55
|
+
*
|
|
56
|
+
* // Without organization
|
|
57
|
+
* getAppCacheDir({ name: "my-cli" });
|
|
58
|
+
* // => ~/.cache/my-cli
|
|
59
|
+
* ```
|
|
60
|
+
*/
|
|
61
|
+
export const getAppCacheDir = (app) => host.resolveAppPaths({ app }).appDir;
|
|
62
|
+
/**
|
|
63
|
+
* Gets a versioned path within the application cache.
|
|
64
|
+
*
|
|
65
|
+
* The version is normalized to always include a 'v' prefix for consistency.
|
|
66
|
+
*
|
|
67
|
+
* @param app - Application identifier
|
|
68
|
+
* @param version - Version string (e.g., "1.0.0" or "v1.0.0")
|
|
69
|
+
* @param name - Name of the cached item
|
|
70
|
+
* @returns Absolute path to the versioned cache location
|
|
71
|
+
* @throws {Error} When the bridge does not load (its load error is the `cause`)
|
|
72
|
+
*
|
|
73
|
+
* @example
|
|
74
|
+
* ```typescript
|
|
75
|
+
* getVersionedCachePath({ name: "my-cli" }, "1.0.0", "binary");
|
|
76
|
+
* // => ~/.cache/my-cli/v1.0.0/binary
|
|
77
|
+
*
|
|
78
|
+
* getVersionedCachePath({ name: "my-cli" }, "v2.0.0", "data.json");
|
|
79
|
+
* // => ~/.cache/my-cli/v2.0.0/data.json
|
|
80
|
+
* ```
|
|
81
|
+
*/
|
|
82
|
+
export const getVersionedCachePath = (app, version, name) => host.resolveAppPaths({ app, version, item: name }).versionedPath;
|
package/package.json
CHANGED
|
@@ -1,6 +1,35 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@eserstack/cache",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "5.0.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "https://github.com/eser/stack",
|
|
8
|
+
"directory": "pkg/@eserstack/cache"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"dist/**/*.js",
|
|
12
|
+
"dist/**/*.d.ts",
|
|
13
|
+
"dist/**/*.json"
|
|
14
|
+
],
|
|
15
|
+
"exports": {
|
|
16
|
+
".": {
|
|
17
|
+
"types": "./dist/mod.d.ts",
|
|
18
|
+
"import": "./dist/mod.js"
|
|
19
|
+
},
|
|
20
|
+
"./xdg": {
|
|
21
|
+
"types": "./dist/xdg.d.ts",
|
|
22
|
+
"import": "./dist/xdg.js"
|
|
23
|
+
}
|
|
24
|
+
},
|
|
25
|
+
"dependencies": {
|
|
26
|
+
"@eserstack/standards": "5.0.0",
|
|
27
|
+
"@eserstack/ajan": "5.0.0"
|
|
28
|
+
},
|
|
29
|
+
"devDependencies": {
|
|
30
|
+
"@eserstack/test-kit": "5.0.0"
|
|
31
|
+
},
|
|
32
|
+
"scripts": {
|
|
33
|
+
"build": "node ../../../etc/scripts/build-library.ts"
|
|
34
|
+
}
|
|
6
35
|
}
|