@chipmobilesdk/rn-chart 0.1.1 → 0.2.1

package/src/contract/value.ts

@@ -1,125 +1,121 @@
-/**
- * Value semantics for @chipmobilesdk/rn-chart.
- *
- * The foundation of the whole contract. Four value classes, carried as a
- * discriminated union with **no numeric field on the three non-value cases**.
- *
- * That shape is deliberate: with a nullable `number`, `value ?? 0` would
- * compile, and turning a gap into a zero is the single most damaging thing a
- * charting library can do to someone's data. Here there is simply no number to
- * read unless the value is known.
- *
- * See specs/007-rn-chart-package/data-model.md §1 (FR-011, FR-012).
- */
-
-/** A real observation, including a genuine `0`. */
-export interface KnownValue {
-	readonly kind: 'known';
-	readonly value: number;
-}
-
-/** We do not know this value. Never rendered as zero, never interpolated. */
-export interface UnknownValue {
-	readonly kind: 'unknown';
-}
-
-/** This value does not apply here. Excluded from totals and proportions. */
-export interface NotApplicableValue {
-	readonly kind: 'notApplicable';
-}
-
-/** Hidden from this viewer: permission, or not enough data to disclose. */
-export interface WithheldValue {
-	readonly kind: 'withheld';
-}
-
-export type ValueState =
-	| KnownValue
-	| UnknownValue
-	| NotApplicableValue
-	| WithheldValue;
-
-export type ValueKind = ValueState['kind'];
-
-const UNKNOWN: UnknownValue = { kind: 'unknown' };
-const NOT_APPLICABLE: NotApplicableValue = { kind: 'notApplicable' };
-const WITHHELD: WithheldValue = { kind: 'withheld' };
-
-export function known(value: number): KnownValue {
-	return { kind: 'known', value };
-}
-
-/**
- * Note: shadows the `unknown` *type* keyword in value position only. TypeScript
- * keeps type and value namespaces separate, so `x: unknown` still means the
- * type even in modules that import this helper.
- */
-export function unknown(): UnknownValue {
-	return UNKNOWN;
-}
-
-export function notApplicable(): NotApplicableValue {
-	return NOT_APPLICABLE;
-}
-
-export function withheld(): WithheldValue {
-	return WITHHELD;
-}
-
-export function isKnown(v: ValueState): v is KnownValue {
-	return v.kind === 'known';
-}
-
-/**
- * True when the value must never reach a rendering, a label, a summary, or an
- * interaction callback (FR-033, FR-053). Withheld values carry no number at
- * all, so this is about intent rather than data hiding.
- */
-export function isWithheld(v: ValueState): v is WithheldValue {
-	return v.kind === 'withheld';
-}
-
-/**
- * True when the point takes part in totals, proportions, and axis domains.
- * `notApplicable` and `withheld` are excluded; excluding either makes a total
- * incomplete (FR-013).
- */
-export function participatesInTotals(v: ValueState): boolean {
-	return v.kind === 'known';
-}
-
-export interface TotalResult {
-	readonly total: number;
-	/** True when any point was excluded, so the total is not the whole picture. */
-	readonly incomplete: boolean;
-	readonly countedPoints: number;
-	readonly excludedPoints: number;
-}
-
-/**
- * Sums known values and reports whether anything was left out (FR-013).
- *
- * `unknown` also excludes and marks the total incomplete: we cannot claim a sum
- * is complete when part of the data is missing.
- */
-export function sumKnown(values: readonly ValueState[]): TotalResult {
-	let total = 0;
-	let counted = 0;
-	let excluded = 0;
-
-	for (const v of values) {
-		if (v.kind === 'known') {
-			total += v.value;
-			counted += 1;
-		} else {
-			excluded += 1;
-		}
-	}
-
-	return {
-		total,
-		incomplete: excluded > 0,
-		countedPoints: counted,
-		excludedPoints: excluded,
-	};
-}
+/**
+ * Value semantics for @chipmobilesdk/rn-chart.
+ *
+ * The foundation of the whole contract. Four value classes, carried as a
+ * discriminated union with **no numeric field on the three non-value cases**.
+ *
+ * That shape is deliberate: with a nullable `number`, `value ?? 0` would
+ * compile, and turning a gap into a zero is the single most damaging thing a
+ * charting library can do to someone's data. Here there is simply no number to
+ * read unless the value is known.
+ *
+ * See specs/007-rn-chart-package/data-model.md §1 (FR-011, FR-012).
+ */
+
+/** A real observation, including a genuine `0`. */
+export interface KnownValue {
+	readonly kind: 'known';
+	readonly value: number;
+}
+
+/** We do not know this value. Never rendered as zero, never interpolated. */
+export interface UnknownValue {
+	readonly kind: 'unknown';
+}
+
+/** This value does not apply here. Excluded from totals and proportions. */
+export interface NotApplicableValue {
+	readonly kind: 'notApplicable';
+}
+
+/** Hidden from this viewer: permission, or not enough data to disclose. */
+export interface WithheldValue {
+	readonly kind: 'withheld';
+}
+
+export type ValueState = KnownValue | UnknownValue | NotApplicableValue | WithheldValue;
+
+export type ValueKind = ValueState['kind'];
+
+const UNKNOWN: UnknownValue = { kind: 'unknown' };
+const NOT_APPLICABLE: NotApplicableValue = { kind: 'notApplicable' };
+const WITHHELD: WithheldValue = { kind: 'withheld' };
+
+export function known(value: number): KnownValue {
+	return { kind: 'known', value };
+}
+
+/**
+ * Note: shadows the `unknown` *type* keyword in value position only. TypeScript
+ * keeps type and value namespaces separate, so `x: unknown` still means the
+ * type even in modules that import this helper.
+ */
+export function unknown(): UnknownValue {
+	return UNKNOWN;
+}
+
+export function notApplicable(): NotApplicableValue {
+	return NOT_APPLICABLE;
+}
+
+export function withheld(): WithheldValue {
+	return WITHHELD;
+}
+
+export function isKnown(v: ValueState): v is KnownValue {
+	return v.kind === 'known';
+}
+
+/**
+ * True when the value must never reach a rendering, a label, a summary, or an
+ * interaction callback (FR-033, FR-053). Withheld values carry no number at
+ * all, so this is about intent rather than data hiding.
+ */
+export function isWithheld(v: ValueState): v is WithheldValue {
+	return v.kind === 'withheld';
+}
+
+/**
+ * True when the point takes part in totals, proportions, and axis domains.
+ * `notApplicable` and `withheld` are excluded; excluding either makes a total
+ * incomplete (FR-013).
+ */
+export function participatesInTotals(v: ValueState): boolean {
+	return v.kind === 'known';
+}
+
+export interface TotalResult {
+	readonly total: number;
+	/** True when any point was excluded, so the total is not the whole picture. */
+	readonly incomplete: boolean;
+	readonly countedPoints: number;
+	readonly excludedPoints: number;
+}
+
+/**
+ * Sums known values and reports whether anything was left out (FR-013).
+ *
+ * `unknown` also excludes and marks the total incomplete: we cannot claim a sum
+ * is complete when part of the data is missing.
+ */
+export function sumKnown(values: readonly ValueState[]): TotalResult {
+	let total = 0;
+	let counted = 0;
+	let excluded = 0;
+
+	for (const v of values) {
+		if (v.kind === 'known') {
+			total += v.value;
+			counted += 1;
+		} else {
+			excluded += 1;
+		}
+	}
+
+	return {
+		total,
+		incomplete: excluded > 0,
+		countedPoints: counted,
+		excludedPoints: excluded,
+	};
+}