@zedtech/zedkit-core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zedtech-fr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @zedtech/zedkit-core
 
-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.
+Foundational helpers with a stable public surface. Original work by the
+same author.
+
+```sh
+pnpm add @zedtech/zedkit-core
+```
+
+```ts
+import { tryCatch } from "@zedtech/zedkit-core";
+
+const parsed = tryCatch(() => JSON.parse(input));
+if (!parsed.ok) return fallback(parsed.error);
+```
+
+## API
+
+- `Result<T, E = Error>` — `{ ok: true, value: T } | { ok: false, error: E }`
+- `ok(value)`, `err(error)`, `isOk(result)`, `isErr(result)`
+- `mapResult(result, fn)`, `unwrapOr(result, fallback)`
+- `tryCatch(fn)`, `tryCatchAsync(fn)` — never swallow; non-`Error` throws
+  become `Error` with `cause` set. Raw `try`/`catch` stays banned
+  everywhere else.
+- `newPrefixedId(prefix)`, `isPrefixedId(id, prefix)` — `"<prefix>_<ulid>"`
+  IDs via a thin wrapper over the `ulid` package (see the
+  [golden rule](../../docs/golden-rule.md)).
+
+Find helpers by need in [CATALOG.md](CATALOG.md).
+
+## Install or copy?
+
+`result` and `try-catch` are tiny and dependency-free: source-copying the
+two files is a sane alternative to installing (MIT allows it). Install
+the package when you also want `ids` (which needs the `ulid`
+dependency) or versioned updates.
+
+## Verify
+
+```sh
+pnpm --filter @zedtech/zedkit-core typecheck && pnpm --filter @zedtech/zedkit-core lint && pnpm --filter @zedtech/zedkit-core build && pnpm --filter @zedtech/zedkit-core test
+```

package/dist/ids.d.ts

@@ -0,0 +1,5 @@
+/** `"<prefix>_<ulid>"`, e.g. `order_01M5Q75SHJ9CVV6E3RBF0FGEM1`. */
+export declare function newPrefixedId(prefix: string): string;
+/** True when `id` is a `newPrefixedId(prefix)` output (shape-checked). */
+export declare function isPrefixedId(id: string, prefix: string): boolean;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAYA,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAMhE"}

package/dist/ids.js

@@ -0,0 +1,23 @@
+// Thin wrapper over the mature `ulid` package (see the golden rule):
+// prefixed, greppable, unconfusable unique IDs.
+import { ulid } from "ulid";
+function assertPrefix(prefix) {
+    if (prefix.length === 0 || prefix.includes("_")) {
+        throw new Error(`invalid id prefix ${JSON.stringify(prefix)}: expected a non-empty string without "_"`);
+    }
+}
+/** `"<prefix>_<ulid>"`, e.g. `order_01M5Q75SHJ9CVV6E3RBF0FGEM1`. */
+export function newPrefixedId(prefix) {
+    assertPrefix(prefix);
+    return `${prefix}_${ulid()}`;
+}
+/** True when `id` is a `newPrefixedId(prefix)` output (shape-checked). */
+export function isPrefixedId(id, prefix) {
+    assertPrefix(prefix);
+    const head = `${prefix}_`;
+    if (!id.startsWith(head))
+        return false;
+    const raw = id.slice(head.length);
+    return raw.length === 26 && /^[0-9A-HJKMNP-TV-Z]{26}$/.test(raw);
+}
+//# sourceMappingURL=ids.js.map

package/dist/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,gDAAgD;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,qBAAqB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,2CAA2C,CACvF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,YAAY,CAAC,MAAM,CAAC,CAAC;IACrB,OAAO,GAAG,MAAM,IAAI,IAAI,EAAE,EAAE,CAAC;AAC/B,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,MAAc;IACrD,YAAY,CAAC,MAAM,CAAC,CAAC;IACrB,MAAM,IAAI,GAAG,GAAG,MAAM,GAAG,CAAC;IAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,OAAO,GAAG,CAAC,MAAM,KAAK,EAAE,IAAI,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACnE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { type Result, err, isErr, isOk, mapResult, ok, unwrapOr } from "./result.js";
+export { normalizeThrown, tryCatch, tryCatchAsync } from "./try-catch.js";
+export { isPrefixedId, newPrefixedId } from "./ids.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { err, isErr, isOk, mapResult, ok, unwrapOr } from "./result.js";
+export { normalizeThrown, tryCatch, tryCatchAsync } from "./try-catch.js";
+export { isPrefixedId, newPrefixedId } from "./ids.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/result.d.ts

@@ -0,0 +1,20 @@
+export type Result<T, E = Error> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+export declare function ok<T>(value: T): Result<T, never>;
+export declare function err<E>(error: E): Result<never, E>;
+export declare function isOk<T, E>(result: Result<T, E>): result is {
+    ok: true;
+    value: T;
+};
+export declare function isErr<T, E>(result: Result<T, E>): result is {
+    ok: false;
+    error: E;
+};
+export declare function mapResult<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+export declare function unwrapOr<T, E>(result: Result<T, E>, fallback: T): T;
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,IAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE5B,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAEhD;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAEjD;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAEjF;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,IAAI;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAEnF;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EACpB,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAClB,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAKd;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAKnE"}

package/dist/result.js

@@ -0,0 +1,25 @@
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}
+export function isOk(result) {
+    return result.ok;
+}
+export function isErr(result) {
+    return !result.ok;
+}
+export function mapResult(result, fn) {
+    if (!result.ok) {
+        return result;
+    }
+    return ok(fn(result.value));
+}
+export function unwrapOr(result, fallback) {
+    if (result.ok) {
+        return result.value;
+    }
+    return fallback;
+}
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,EAAE,CAAI,KAAQ;IAC5B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,GAAG,CAAI,KAAQ;IAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,IAAI,CAAO,MAAoB;IAC7C,OAAO,MAAM,CAAC,EAAE,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,KAAK,CAAO,MAAoB;IAC9C,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,MAAoB,EACpB,EAAmB;IAEnB,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,QAAQ,CAAO,MAAoB,EAAE,QAAW;IAC9D,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/try-catch.d.ts

@@ -0,0 +1,5 @@
+import { type Result } from "./result.js";
+export declare function normalizeThrown(thrown: unknown): Error;
+export declare function tryCatch<T>(fn: () => T): Result<T, Error>;
+export declare function tryCatchAsync<T>(fn: () => Promise<T>): Promise<Result<T, Error>>;
+//# sourceMappingURL=try-catch.d.ts.map

package/dist/try-catch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"try-catch.d.ts","sourceRoot":"","sources":["../src/try-catch.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAEnD,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,KAAK,CAQtD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAMzD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAKhF"}

package/dist/try-catch.js

@@ -0,0 +1,28 @@
+// Original work by the same author.
+// This file is the ONE documented exception to the TryStatement lint ban:
+// it implements the wrappers everything else must use.
+import { err, ok } from "./result.js";
+export function normalizeThrown(thrown) {
+    if (thrown instanceof Error) {
+        return thrown;
+    }
+    const message = typeof thrown === "string" ? thrown : String(thrown);
+    const wrapped = new Error(message);
+    wrapped.cause = thrown;
+    return wrapped;
+}
+export function tryCatch(fn) {
+    try {
+        return ok(fn());
+    }
+    catch (thrown) {
+        return err(normalizeThrown(thrown));
+    }
+}
+export function tryCatchAsync(fn) {
+    return Promise.resolve()
+        .then(() => fn())
+        .then((value) => ok(value))
+        .catch((thrown) => err(normalizeThrown(thrown)));
+}
+//# sourceMappingURL=try-catch.js.map

package/dist/try-catch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"try-catch.js","sourceRoot":"","sources":["../src/try-catch.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,0EAA0E;AAC1E,uDAAuD;AACvD,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,aAAa,CAAC;AAEnD,MAAM,UAAU,eAAe,CAAC,MAAe;IAC7C,IAAI,MAAM,YAAY,KAAK,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC;IACvB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAI,EAAW;IACrC,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,OAAO,GAAG,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAI,EAAoB;IACnD,OAAO,OAAO,CAAC,OAAO,EAAE;SACrB,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;SAChB,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;SAC1B,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@zedtech/zedkit-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "description": "Foundational helpers: Result, tryCatch, prefixed IDs. Original work by the same author.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zedtech-fr/zedkit",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": "./src/*"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ulid": "3.0.2"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vitest": "2.1.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.tests.json",
+    "lint": "eslint src tests"
+  }
 }