@healthzkit/memcached 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @healthzkit/memcached
 
-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.
+Memcached health adapters for [healthzkit](https://github.com/alasti-company/healthzkit.dev). Checks return `ok` with `metadata.latencyMs`, or `fail` with an `Error`.
+
+## Install
+
+```bash
+npm install healthzkit @healthzkit/memcached
+# Install the client you use:
+npm install memcached
+# or:
+npm install memjs
+```
+
+The package is ESM-only and requires Node.js 22.12+. The clients are optional peers. TypeScript projects should also install `@types/memcached` or `@types/memjs` for their chosen client.
+
+## Quick start
+
+```ts
+import { createHealthKit } from "healthzkit";
+import { memcachedAdapter } from "@healthzkit/memcached/memcached";
+
+const kit = createHealthKit({
+  checks: [
+    {
+      name: "memcached",
+      type: ["readiness"],
+      adapter: memcachedAdapter({ servers: "localhost:11211" }),
+    },
+  ],
+});
+```
+
+Use a subpath import to load only the client you install. Both factories are also exported from `@healthzkit/memcached`; client libraries load lazily when you use the `servers` option.
+
+| Client                                             | Import                            | Factory            | Check                                                               |
+| -------------------------------------------------- | --------------------------------- | ------------------ | ------------------------------------------------------------------- |
+| [memcached](https://github.com/3rd-Eden/memcached) | `@healthzkit/memcached/memcached` | `memcachedAdapter` | Read-only `VERSION` across the client's server list                 |
+| [memjs](https://github.com/memcachier/memjs)       | `@healthzkit/memcached/memjs`     | `memjsAdapter`     | Read-only `GET` of a probe key on the server selected by the client |
+
+## memcached
+
+```ts
+import Memcached from "memcached";
+import { memcachedAdapter } from "@healthzkit/memcached/memcached";
+
+// Create and reuse an internal client.
+memcachedAdapter({
+  servers: ["localhost:11211", "localhost:11212"],
+  options: { timeout: 1000, retries: 1 },
+});
+
+// Reuse your application's client.
+const client = new Memcached("localhost:11211");
+memcachedAdapter({ client });
+```
+
+`servers` accepts a `host:port` string, an array of locations, or an object mapping locations to weights. The adapter requires non-empty locations. `options` forwards the client's constructor options, with `retries: 1` by default. Its `timeout` is in milliseconds.
+
+The adapter fails on any reported server error or an empty version response. This client uses the ASCII protocol and does not support SASL authentication.
+
+## memjs
+
+```ts
+import { Client } from "memjs";
+import { memjsAdapter } from "@healthzkit/memcached/memjs";
+
+memjsAdapter({
+  servers: "localhost:11211,localhost:11212",
+  options: { timeout: 0.5, username: "user", password: "password" },
+  key: "healthzkit:healthcheck",
+});
+
+const client = Client.create("localhost:11211");
+memjsAdapter({ client });
+```
+
+`servers` is a non-empty comma-separated string in memjs format: `[user:pass@]host[:port]`. `options` forwards client and server options, with `retries: 1` by default. Its `timeout` and `conntimeout` are in seconds.
+
+`key` defaults to `healthzkit:healthcheck`. It must be 1–250 UTF-8 bytes without whitespace or NUL. A missing key is healthy: the server responded successfully. The adapter never writes, deletes, or requires a pre-existing key. It checks the server chosen for that key, so it does not verify every cluster member. Client failover settings also affect which server responds.
+
+## Metadata and client ownership
+
+Both adapters accept a synchronous or asynchronous metadata hook:
+
+```ts
+memcachedAdapter({
+  servers: "localhost:11211",
+  metadata: () => ({ region: "us-west" }),
+});
+```
+
+The hook receives the resolved client after the check succeeds. Its fields merge into the result; measured `latencyMs` takes precedence. Hook errors fail the check.
+
+Use either `client` or `servers` with optional `options`. Internally created clients are lazy and reused, including across concurrent checks. Adapters keep clients open between checks and do not close supplied clients. If you need explicit shutdown control, supply your own client and call `client.end()` for memcached or `client.close()` for memjs when your application stops.
+
+Use [Scheduling](https://healthzkit.dev/guide/scheduling) to cache readiness results when you want to avoid checking the cache on every HTTP request.
+
+## Development
+
+```bash
+vp test
+vp check
+vp run build
+```

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { MemcachedAdapterOptions, MemcachedAdapterOptionsWithClient, MemcachedAdapterOptionsWithServers, memcachedAdapter } from "./memcached.mjs";
+import { MemjsAdapterOptions, MemjsAdapterOptionsWithClient, MemjsAdapterOptionsWithServers, memjsAdapter } from "./memjs.mjs";
+export { type MemcachedAdapterOptions, type MemcachedAdapterOptionsWithClient, type MemcachedAdapterOptionsWithServers, type MemjsAdapterOptions, type MemjsAdapterOptionsWithClient, type MemjsAdapterOptionsWithServers, memcachedAdapter, memjsAdapter };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{memcachedAdapter as e}from"./memcached.mjs";import{memjsAdapter as t}from"./memjs.mjs";export{e as memcachedAdapter,t as memjsAdapter};

package/dist/memcached.d.mts

@@ -0,0 +1,21 @@
+import { HealthAdapter, MetadataFn } from "@healthzkit/shared";
+import Memcached from "memcached";
+//#region src/memcached.d.ts
+interface BaseMemcachedOptions {
+  metadata?: MetadataFn<Memcached>;
+}
+interface MemcachedAdapterOptionsWithClient extends BaseMemcachedOptions {
+  client: Memcached;
+  servers?: never;
+  options?: never;
+}
+interface MemcachedAdapterOptionsWithServers extends BaseMemcachedOptions {
+  servers: string | string[] | Record<string, number>;
+  options?: Memcached.options;
+  client?: never;
+}
+type MemcachedAdapterOptions = MemcachedAdapterOptionsWithClient | MemcachedAdapterOptionsWithServers;
+/** Check every configured server using the read-only VERSION command. */
+declare function memcachedAdapter(options: MemcachedAdapterOptions): HealthAdapter;
+//#endregion
+export { MemcachedAdapterOptions, MemcachedAdapterOptionsWithClient, MemcachedAdapterOptionsWithServers, memcachedAdapter };

package/dist/memcached.mjs

@@ -0,0 +1 @@
+import{buildErrorResult as e,buildResult as t}from"@healthzkit/shared";function n(n){let r;async function i(){if(n.client!==void 0)return n.client;let e=n.servers,t=typeof e==`string`?[e]:Array.isArray(e)?e:Object.keys(e??{});if(t.length===0||t.some(e=>!e.trim()))throw Error(`memcachedAdapter: provide non-empty servers or a client`);return r??=import(`memcached`).then(({default:t})=>new t(e,{retries:1,...n.options})).catch(e=>{throw r=void 0,e}),r}return{async check(){try{let e=await i(),r=Date.now();await new Promise((t,n)=>{e.version((e,r)=>{(Array.isArray(e)?e.length>0:e)?n(e):!Array.isArray(r)||r.length===0||r.some(e=>!e||!e.version)?n(Error(`memcachedAdapter: no version returned by a server`)):t()})});let a=Date.now()-r;return t(a,await n.metadata?.(e))}catch(t){return e(t)}}}}export{n as memcachedAdapter};

package/dist/memjs.d.mts

@@ -0,0 +1,24 @@
+import { HealthAdapter, MetadataFn } from "@healthzkit/shared";
+import { Client, ClientOptions, ServerOptions } from "memjs";
+//#region src/memjs.d.ts
+interface BaseMemjsOptions {
+  /** Key to read. A cache miss is healthy. Defaults to "healthzkit:healthcheck". */
+  key?: string;
+  metadata?: MetadataFn<Client>;
+}
+interface MemjsAdapterOptionsWithClient extends BaseMemjsOptions {
+  client: Client;
+  servers?: never;
+  options?: never;
+}
+interface MemjsAdapterOptionsWithServers extends BaseMemjsOptions {
+  /** Comma-separated servers in memjs format, optionally including credentials. */
+  servers: string;
+  options?: ClientOptions & ServerOptions;
+  client?: never;
+}
+type MemjsAdapterOptions = MemjsAdapterOptionsWithClient | MemjsAdapterOptionsWithServers;
+/** Read a key from the server selected by memjs without writing to the cache. */
+declare function memjsAdapter(options: MemjsAdapterOptions): HealthAdapter;
+//#endregion
+export { MemjsAdapterOptions, MemjsAdapterOptionsWithClient, MemjsAdapterOptionsWithServers, memjsAdapter };

package/dist/memjs.mjs

@@ -0,0 +1 @@
+import{buildErrorResult as e,buildResult as t}from"@healthzkit/shared";function n(n){let r;async function i(){if(n.client!==void 0)return n.client;if(!n.servers?.trim()||n.servers.split(`,`).some(e=>!e.trim()))throw Error(`memjsAdapter: provide non-empty servers or a client`);return r??=import(`memjs`).then(({Client:e})=>e.create(n.servers,{retries:1,...n.options})).catch(e=>{throw r=void 0,e}),r}return{async check(){try{let e=n.key??`healthzkit:healthcheck`;if(!e||/\s/.test(e)||e.includes(`\0`)||Buffer.byteLength(e)>250)throw Error(`memjsAdapter: key must be 1–250 bytes without whitespace or NUL`);let r=await i(),a=Date.now();await r.get(e);let o=Date.now()-a;return t(o,await n.metadata?.(r))}catch(t){return e(t)}}}}export{n as memjsAdapter};

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@healthzkit/memcached",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Memcached health-check adapters for healthzkit (memcached and memjs).",
+  "keywords": [
+    "health-check",
+    "healthcheck",
+    "healthzkit",
+    "kubernetes",
+    "liveness",
+    "memcached",
+    "memjs",
+    "probe",
+    "readiness"
+  ],
+  "homepage": "https://healthzkit.dev",
+  "bugs": {
+    "url": "https://github.com/alasti-company/healthzkit.dev/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Alasti Company",
+    "url": "https://healthzkit.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alasti-company/healthzkit.dev",
+    "directory": "packages/memcached"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./memcached": "./dist/memcached.mjs",
+    "./memjs": "./dist/memjs.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "dependencies": {
+    "@healthzkit/shared": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/memcached": "^2.2.10",
+    "@types/memjs": "^1.3.3",
+    "@types/node": "catalog:",
+    "@typescript/native-preview": "catalog:",
+    "bumpp": "catalog:",
+    "healthzkit": "workspace:*",
+    "memcached": "^2.2.2",
+    "memjs": "^1.3.2",
+    "typescript": "catalog:",
+    "vite-plus": "catalog:"
+  },
+  "peerDependencies": {
+    "memcached": ">=2.2.2",
+    "memjs": ">=1.3.2"
+  },
+  "peerDependenciesMeta": {
+    "memcached": {
+      "optional": true
+    },
+    "memjs": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}