@sandlada/result 0.0.1-20260701.a

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].
+
+Community Impact Guidelines were inspired by 
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available 
+at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kai-Orion & Sandlada
+
+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

@@ -0,0 +1,183 @@
+# @sandlada/jss
+
+一個簡單的 CSS-in-JS 函式庫，提供兩類工具來管理 CSS 自訂屬性（變數）：
+
+- **define 系列** — 產生 CSS 宣告（`--name: value`），用於輸出到樣式表
+- **use 系列** — 產生 `var()` 引用（`var(--name, fallback)`），用於組合進其他宣告中
+
+完整文件請參閱 [docs/README.md](./docs/README.md)。
+
+## 安裝
+
+```bash
+npm install @sandlada/jss
+```
+
+專案使用 TypeScript 6 + ESM，匯入即可獲得完整的型別推斷。
+
+---
+
+## define 系列 — 產生 CSS 宣告
+
+| 函式                                                   | 說明                                                                                                           | 文件                                                                                                   |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `defineVars(name, value)`                              | 基本變數定義，回傳字串陣列                                                                                     | [docs/define-vars.md](./docs/define-vars.md)                                                           |
+| `defineLogicalBorderRadiusVars(base, value, options?)` | 展開為四個邏輯角（`start-start` / `start-end` / `end-start` / `end-end`），回傳陣列，支援 `{ semi?, prefix? }` | [docs/define-logical-border-radius-vars.md](./docs/define-logical-border-radius-vars.md)               |
+| `defineLogicalBorderRadiusVarsRecord(base, value)`     | 同上，但回傳 Record 物件                                                                                       | [docs/define-logical-border-radius-vars-record.md](./docs/define-logical-border-radius-vars-record.md) |
+| `defineTokenRefsRecord(tokens, options?)`              | 將設計 Token 綁定為內部變數（`--_key: var(--key, value)`），支援形狀屬性展開與 `{ prefix? }`                   | [docs/define-token-refs-record.md](./docs/define-token-refs-record.md)                                 |
+| `defineOverrides(source, overrides)(prefix?)`          | 型別安全的樣式覆蓋輔助，Curried API，可傳入 `null` 跳過型別約束                                                | [docs/define-overrides.md](./docs/define-overrides.md)                                                 |
+
+```ts
+import { defineVars } from '@sandlada/jss'
+
+// ['--color: red']
+defineVars('color', 'red')
+
+// ['--color: red', '--bg-color: blue']
+defineVars({ color: 'red', 'bg-color': 'blue' })
+
+// 第三個參數 true 加上分號尾綴
+defineVars('color', 'red', true) // ['--color: red;']
+```
+
+```ts
+import { defineTokenRefsRecord } from '@sandlada/jss'
+
+const AppTokens = {
+  'button-text-color': 'red',
+  'button-bg-color': 'white',
+  'button-shape': 'var(--md-sys-shape-corner-full, 9999px)',
+} as const
+
+// 將設計 Token 綁定為內部變數：
+// { '--_button-text-color': 'var(--button-text-color, red)', ... }
+defineTokenRefsRecord(AppTokens)
+
+// 使用 prefix 為所有 token 加上前綴：
+defineTokenRefsRecord(AppTokens, { prefix: '--md-badge' })
+// { '--_button-text-color': 'var(--md-badge-button-text-color, red)', ... }
+
+// 展開形狀屬性為四個邏輯角：
+defineTokenRefsRecord(AppTokens, { expandShapes: ['button-shape'] })
+// {
+//   '--_button-text-color': 'var(--button-text-color, red)',
+//   '--_button-shape-start-start': 'var(--button-shape-start-start, var(--md-sys-shape-corner-full, 9999px))',
+//   '--_button-shape-start-end': 'var(--button-shape-start-end, ...)',
+//   '--_button-shape-end-start': 'var(--button-shape-end-start, ...)',
+//   '--_button-shape-end-end': 'var(--button-shape-end-end, ...)',
+// }
+
+// 加入基底變數作為中繼備援（兩層 var() 遞迴）：
+defineTokenRefsRecord(AppTokens, { expandShapes: ['button-shape'], useBaseFallback: true })
+// {
+//   '--_button-shape-start-start': 'var(--button-shape-start-start, var(--button-shape, var(--md-sys-shape-corner-full, 9999px)))',
+//   ...
+// }
+```
+
+---
+
+## defineOverrides — 型別安全的樣式覆蓋
+
+```ts
+import { defineOverrides } from '@sandlada/jss'
+
+const FocusRing = {
+  'outline-color': 'red',
+  'outline-width': '2px',
+} as const
+
+// 型別安全模式：從 source 推導鍵值約束，所有鍵皆為可選
+// { 'outline-color': 'blue' }
+defineOverrides(FocusRing, { 'outline-color': 'blue' })()
+
+// 套用 CSS 變數前綴
+// { '--my-comp-outline-color': 'blue' }
+defineOverrides(FocusRing, { 'outline-color': 'blue' })('--my-comp')
+
+// 部分覆蓋或空物件皆可
+defineOverrides(FocusRing, {})()
+
+// 無型別約束模式：source 傳入 null
+defineOverrides(null, { 'outline-color': 'blue' })()
+
+// 實際使用：覆蓋共享元件樣式
+const CompB = {
+  'bg-color': 'blue',
+  ...defineOverrides(FocusRing, { 'outline-color': 'blue' })('--my-comp'),
+} as const
+// { 'bg-color': 'blue', '--my-comp-outline-color': 'blue' }
+```
+
+---
+
+## 通用選項
+
+部分函式支援第二個（或第三個）參數傳入 `JSSOptions` 物件來控制行為：
+
+```ts
+interface JSSOptions {
+  semi?: boolean   // 是否在結尾加上分號（;）
+  prefix?: string  // CSS 變數名稱前綴（例如 '--md-badge'）
+}
+```
+
+**`semi`** — 加上分號尾綴，適用於需要 inline style 語句的場景。
+
+**`prefix`** — 為產生的 CSS 變數名稱加上自訂前綴。例如使用 `{ prefix: '--md-badge' }` 時，
+`useVars('color-primary', 'blue', { prefix: '--md-badge' })` 會輸出 `var(--md-badge-color-primary, blue)`，
+取代預設的 `var(--color-primary, blue)`。
+
+> **注意：** `prefix` 僅影響 CSS 變數的**名稱部分**，不影響 Record 的 JavaScript 鍵名。
+> 支援 prefix 的函式：`useVars`、`useVarsRecord`、`useInternalVarsRecord`、`useLogicalBorderRadiusVars`、
+> `useLogicalBorderRadiusVarsRecord`、`defineLogicalBorderRadiusVars`、`defineTokenRefsRecord`。
+
+---
+
+## use 系列 — 產生 `var()` 引用
+
+| 函式                                                           | 說明                                                                 | 文件                                                                                             |
+| -------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `useVars(name, fallback, options?)`                            | 基本變數引用，回傳陣列，支援 `{ semi?, prefix? }`                    | [docs/use-vars.md](./docs/use-vars.md)                                                           |
+| `useVarsRecord(name, fallback, options?)`                      | 基本變數引用，回傳 Record，支援 `{ semi?, prefix? }`                 | [docs/use-vars-record.md](./docs/use-vars-record.md)                                             |
+| `useInternalVars(name, fallback)`                              | 內部變數（`--_` 前綴）引用，回傳陣列                                 | [docs/use-internal-vars.md](./docs/use-internal-vars.md)                                         |
+| `useInternalVarsRecord(name, fallback, options?)`              | 內部變數引用，回傳 Record，支援 `{ semi?, prefix? }`                 | [docs/use-internal-vars-record.md](./docs/use-internal-vars-record.md)                           |
+| `useLogicalBorderRadiusVars(corner, fallback, options?)`       | 邏輯角變數（兩層 `var()` 遞迴），回傳陣列，支援 `{ semi?, prefix? }` | [docs/use-logical-border-radius-vars.md](./docs/use-logical-border-radius-vars.md)               |
+| `useLogicalBorderRadiusVarsRecord(corner, fallback, options?)` | 邏輯角變數，回傳 Record，支援 `{ semi?, prefix? }`                   | [docs/use-logical-border-radius-vars-record.md](./docs/use-logical-border-radius-vars-record.md) |
+
+```ts
+import { useVars } from '@sandlada/jss'
+
+// ['var(--color-primary, blue)']
+useVars('color-primary', 'blue')
+
+// 支援 `var()` 遞迴鏈：
+// ['var(--a, var(--b, var(--c, default-value)))']
+useVars(['a', 'b', 'c'], 'default-value')
+
+// Record 模式自動剝除 -- 前綴作為鍵名：
+// { 'color-primary': 'var(--color-primary, blue)' }
+useVarsRecord('--color-primary', 'blue')
+
+// 使用 prefix 選項為所有變數名稱加上前綴：
+// ['var(--md-badge-color-primary, blue)']
+useVars('color-primary', 'blue', { prefix: '--md-badge' })
+
+// ['var(--md-badge-a, var(--md-badge-b, var(--md-badge-c, default-value)))']
+useVars(['a', 'b', 'c'], 'default-value', { prefix: '--md-badge' })
+```
+
+---
+
+## 開發
+
+```bash
+# 安裝依賴
+npm install
+
+# 執行測試
+npx vitest
+
+# 型別檢查
+npx tsc --noEmit
+```

package/SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported Versions
+
+Security updates are only applied to the latest published version.
+
+## Reporting a Vulnerability
+
+Report vulnerabilities in a private
+[GitHub security advisory](https://github.com/sandlada/result/security/advisories).
+
+**Please do not disclose security vulnerabilities in public issues.**

package/build/IResult.d.ts

@@ -0,0 +1,16 @@
+/**
+ * IResult — base result contract.
+ *
+ * Every result exposes an error, a success flag, and a failure flag.
+ * The error is always accessible; on success it returns an internal sentinel.
+ * Consumers should check `isSuccess` before interpreting `error`.
+ */
+export interface IResult<TError = Error> {
+    /** Always accessible. On success, returns the NONE sentinel. */
+    readonly error: TError;
+    /** `true` if the operation succeeded. */
+    readonly isSuccess: boolean;
+    /** `true` if the operation failed. Always the negation of `isSuccess`. */
+    readonly isFailure: boolean;
+}
+//# sourceMappingURL=IResult.d.ts.map

package/build/IResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IResult.d.ts","sourceRoot":"","sources":["../src/IResult.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,OAAO,CAAC,MAAM,GAAG,KAAK;IACnC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC/B"}

package/build/IResult.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IResult.js.map

package/build/IResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IResult.js","sourceRoot":"","sources":["../src/IResult.ts"],"names":[],"mappings":""}

package/build/IResultOfT.d.ts

@@ -0,0 +1,12 @@
+import type { IResult } from './IResult.js';
+/**
+ * IResultOfT<TValue, TError> — a result that carries a success value.
+ *
+ * Extends the base {@link IResult} contract with a `value` property.
+ * Accessing `value` on a failure result throws a TypeError.
+ */
+export interface IResultOfT<TValue, TError = Error> extends IResult<TError> {
+    /** The success payload. Throws `TypeError` if accessed on a failure. */
+    readonly value: TValue;
+}
+//# sourceMappingURL=IResultOfT.d.ts.map

package/build/IResultOfT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IResultOfT.d.ts","sourceRoot":"","sources":["../src/IResultOfT.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAE,SAAQ,OAAO,CAAC,MAAM,CAAC;IACvE,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B"}

package/build/IResultOfT.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IResultOfT.js.map

package/build/IResultOfT.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IResultOfT.js","sourceRoot":"","sources":["../src/IResultOfT.ts"],"names":[],"mappings":""}

package/build/Result.d.ts

@@ -0,0 +1,53 @@
+import type { IResult } from './IResult.js';
+import type { IResultOfT } from './IResultOfT.js';
+/**
+ * Base class implementing the core result invariant.
+ *
+ * ## Invariant (enforced by constructor)
+ * - `isSuccess && error !== NONE` → **throw** (success must not carry a real error)
+ * - `!isSuccess && error === NONE` → **throw** (failure must carry a real error)
+ *
+ * Users do not instantiate this class directly.
+ * Use the static factory methods: {@link Result.Success}, {@link Result.Failure}.
+ */
+export declare class Result<TError = Error> implements IResult<TError> {
+    readonly isSuccess: boolean;
+    readonly error: TError;
+    /**
+     * **Internal.** Validates the mutual-exclusivity invariant.
+     *
+     * @throws If the invariant is violated (success with real error, or failure with NONE).
+     */
+    protected constructor(isSuccess: boolean, error?: TError);
+    get isFailure(): boolean;
+    /** Creates a void success result (no value). */
+    static Success(): IResult;
+    /** Creates a success result carrying a value. Type is inferred. */
+    static Success<TValue>(value: TValue): IResultOfT<TValue>;
+    /** Creates a void failure result. */
+    static Failure(error: Error): IResult;
+    /** Creates a typed failure result. `TValue` must be specified. */
+    static Failure<TValue, TError>(error: TError): IResultOfT<TValue, TError>;
+}
+/**
+ * Generic result carrying a success value.
+ *
+ * Extends the {@link Result} base class and implements
+ * {@link IResultOfT}.
+ *
+ * Users do not instantiate this class directly.
+ * Use {@link Result.Success} or {@link Result.Failure}.
+ */
+export declare class ResultOfT<TValue, TError = Error> extends Result<TError> implements IResultOfT<TValue, TError> {
+    #private;
+    /**
+     * **Internal.** Constructed by {@link Result} factory methods.
+     */
+    constructor(value?: TValue, isSuccess?: boolean, error?: TError);
+    /**
+     * The success payload.
+     * @throws {TypeError} If this result represents a failure.
+     */
+    get value(): TValue;
+}
+//# sourceMappingURL=Result.d.ts.map

package/build/Result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Result.d.ts","sourceRoot":"","sources":["../src/Result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAWlD;;;;;;;;;GASG;AACH,qBAAa,MAAM,CAAC,MAAM,GAAG,KAAK,CAAE,YAAW,OAAO,CAAC,MAAM,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,SAAS,aAAa,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,EAavD;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,gDAAgD;IAChD,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC;IAC1B,mEAAmE;IACnE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAQ1D,qCAAqC;IACrC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IACtC,kEAAkE;IAClE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAO7E;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAE,SAAQ,MAAM,CAAC,MAAM,CAAE,YAAW,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC;;IAGvG;;OAEG;IACH,YAAY,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,EAO9D;IAED;;;OAGG;IACH,IAAI,KAAK,IAAI,MAAM,CAOlB;CACJ"}

package/build/Result.js

@@ -0,0 +1,83 @@
+/**
+ * Internal sentinel used for the `error` property of a success result.
+ *
+ * Uses `Symbol.for()` so it survives module reloads in dev.
+ * Cast to `TError` so it satisfies the type system while being
+ * distinguishable from a real user-supplied error.
+ */
+const NONE = Symbol.for('result:none');
+/**
+ * Base class implementing the core result invariant.
+ *
+ * ## Invariant (enforced by constructor)
+ * - `isSuccess && error !== NONE` → **throw** (success must not carry a real error)
+ * - `!isSuccess && error === NONE` → **throw** (failure must carry a real error)
+ *
+ * Users do not instantiate this class directly.
+ * Use the static factory methods: {@link Result.Success}, {@link Result.Failure}.
+ */
+export class Result {
+    isSuccess;
+    error;
+    /**
+     * **Internal.** Validates the mutual-exclusivity invariant.
+     *
+     * @throws If the invariant is violated (success with real error, or failure with NONE).
+     */
+    constructor(isSuccess, error) {
+        this.isSuccess = isSuccess;
+        if (isSuccess && error !== NONE) {
+            throw new TypeError('Result invariant violated: success must not carry a real error.');
+        }
+        if (!isSuccess && error === NONE) {
+            throw new TypeError('Result invariant violated: failure must carry a real error.');
+        }
+        this.error = error;
+    }
+    get isFailure() {
+        return !this.isSuccess;
+    }
+    static Success(value) {
+        if (arguments.length === 0) {
+            return new Result(true, NONE);
+        }
+        return new ResultOfT(value, true);
+    }
+    static Failure(error) {
+        if (error === undefined) {
+            throw new TypeError('Result.Failure requires an error argument.');
+        }
+        return new ResultOfT(undefined, false, error);
+    }
+}
+/**
+ * Generic result carrying a success value.
+ *
+ * Extends the {@link Result} base class and implements
+ * {@link IResultOfT}.
+ *
+ * Users do not instantiate this class directly.
+ * Use {@link Result.Success} or {@link Result.Failure}.
+ */
+export class ResultOfT extends Result {
+    #value;
+    /**
+     * **Internal.** Constructed by {@link Result} factory methods.
+     */
+    constructor(value, isSuccess, error) {
+        const sentinelError = NONE;
+        super(isSuccess ?? true, isSuccess === false ? error : sentinelError);
+        this.#value = value;
+    }
+    /**
+     * The success payload.
+     * @throws {TypeError} If this result represents a failure.
+     */
+    get value() {
+        if (!this.isSuccess) {
+            throw new TypeError('Cannot access value on a failure result. Check isSuccess before accessing value.');
+        }
+        return this.#value;
+    }
+}
+//# sourceMappingURL=Result.js.map

package/build/Result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Result.js","sourceRoot":"","sources":["../src/Result.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,IAAI,GAAkB,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,OAAO,MAAM;IACN,SAAS,CAAU;IACnB,KAAK,CAAS;IAEvB;;;;OAIG;IACH,YAAsB,SAAkB,EAAE,KAAc;QACpD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,SAAS,IAAI,KAAK,KAAM,IAA0B,EAAE,CAAC;YACrD,MAAM,IAAI,SAAS,CACf,iEAAiE,CACpE,CAAC;QACN,CAAC;QACD,IAAI,CAAC,SAAS,IAAI,KAAK,KAAM,IAA0B,EAAE,CAAC;YACtD,MAAM,IAAI,SAAS,CACf,6DAA6D,CAChE,CAAC;QACN,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,KAAe,CAAC;IACjC,CAAC;IAED,IAAI,SAAS;QACT,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;IAC3B,CAAC;IAMD,MAAM,CAAC,OAAO,CAAS,KAAc;QACjC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,IAAI,MAAM,CAAQ,IAAI,EAAG,IAAyB,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,IAAI,SAAS,CAAgB,KAAM,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;IAMD,MAAM,CAAC,OAAO,CAAiB,KAAc;QACzC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,IAAI,SAAS,CAAiB,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAClE,CAAC;CACJ;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,SAAkC,SAAQ,MAAc;IACxD,MAAM,CAAqB;IAEpC;;OAEG;IACH,YAAY,KAAc,EAAE,SAAmB,EAAE,KAAc;QAC3D,MAAM,aAAa,GAAI,IAA0B,CAAC;QAClD,KAAK,CACD,SAAS,IAAI,IAAI,EACjB,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,KAAM,CAAC,CAAC,CAAC,aAAa,CAC/C,CAAC;QACF,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACxB,CAAC;IAED;;;OAGG;IACH,IAAI,KAAK;QACL,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YAClB,MAAM,IAAI,SAAS,CACf,kFAAkF,CACrF,CAAC;QACN,CAAC;QACD,OAAO,IAAI,CAAC,MAAgB,CAAC;IACjC,CAAC;CACJ"}

package/build/ResultOfT.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export of {@link ResultOfT} from the main {@link Result} module.
+ *
+ * The generic class lives alongside {@link Result} in `Result.ts` to avoid
+ * circular dependencies. This file keeps it discoverable at the expected path.
+ */
+export { ResultOfT } from './Result.js';
+//# sourceMappingURL=ResultOfT.d.ts.map

package/build/ResultOfT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResultOfT.d.ts","sourceRoot":"","sources":["../src/ResultOfT.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/build/ResultOfT.js

@@ -0,0 +1,8 @@
+/**
+ * Re-export of {@link ResultOfT} from the main {@link Result} module.
+ *
+ * The generic class lives alongside {@link Result} in `Result.ts` to avoid
+ * circular dependencies. This file keeps it discoverable at the expected path.
+ */
+export { ResultOfT } from './Result.js';
+//# sourceMappingURL=ResultOfT.js.map

package/build/ResultOfT.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResultOfT.js","sourceRoot":"","sources":["../src/ResultOfT.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export type { IResult } from './IResult.js';
+export type { IResultOfT } from './IResultOfT.js';
+export { Result } from './Result.js';
+export { ResultOfT } from './ResultOfT.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/build/index.js

@@ -0,0 +1,3 @@
+export { Result } from './Result.js';
+export { ResultOfT } from './ResultOfT.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@sandlada/result",
+    "version": "0.0.1-20260701.a",
+    "description": "Type-safe Result pattern for TypeScript — explicit error handling without exceptions",
+    "type": "module",
+    "main": "./build/index.js",
+    "types": "./build/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./build/index.d.ts",
+            "default": "./build/index.js"
+        }
+    },
+    "files": [
+        "build/",
+        "README.md",
+        "LICENSE",
+        "CODE_OF_CONDUCT.md",
+        "SECURITY.md"
+    ],
+    "scripts": {
+        "build": "tsgo --project tsconfig.json",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "keywords": [
+        "result",
+        "either",
+        "error-handling",
+        "functional",
+        "typescript"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "author": "Kai-Orion & Sandlada",
+    "license": "MIT",
+    "devDependencies": {
+        "@typescript/native-preview": "^7.0.0-dev.20260630.1",
+        "vitest": "^4.1.9"
+    }
+}