@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 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
- # Temporary Holding Version
1
+ # 📦 [@eserstack/cache](./)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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).
@@ -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
+ }
@@ -0,0 +1,2 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ export {};
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": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
  }