@jjlmoya/utils-aquarium 1.65.0 → 1.66.0

package/src/tool/aquariumSaltDosingCalculator/logic.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_SALT_DOSING_INPUT,
+  calculateSaltDosing,
+  gallonsToLitres,
+  gramsPerLitreToOuncesPerGallon,
+  litresToGallons,
+  ouncesPerGallonToGramsPerLitre,
+} from './logic';
+
+describe('aquarium salt dosing logic', () => {
+  it('calculates product mass for preparing new water', () => {
+    const result = calculateSaltDosing(DEFAULT_SALT_DOSING_INPUT);
+    expect(result).toEqual({ ok: true, value: expect.objectContaining({ action: 'prepare', amountLitres: 20, amountGrams: 720 }) });
+  });
+
+  it('estimates the salt needed to raise an existing tank', () => {
+    const result = calculateSaltDosing({ ...DEFAULT_SALT_DOSING_INPUT, mode: 'correct', volumeLitres: 100, currentSalinityPpt: 30, targetSalinityPpt: 35 });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.action).toBe('raise');
+      expect(result.value.amountGrams).toBeCloseTo(514.2857142857143, 8);
+    }
+  });
+
+  it('calculates the matching water replacement to lower salinity', () => {
+    const result = calculateSaltDosing({ ...DEFAULT_SALT_DOSING_INPUT, mode: 'correct', volumeLitres: 100, currentSalinityPpt: 40, targetSalinityPpt: 35 });
+    expect(result).toEqual({ ok: true, value: expect.objectContaining({ action: 'lower', amountLitres: 12.5 }) });
+  });
+
+  it('returns no action when the target already matches', () => {
+    const result = calculateSaltDosing({ ...DEFAULT_SALT_DOSING_INPUT, mode: 'correct', currentSalinityPpt: 35 });
+    expect(result).toEqual({ ok: true, value: expect.objectContaining({ action: 'target', amountLitres: 0, amountGrams: 0 }) });
+  });
+
+  it('rejects invalid and non-finite values', () => {
+    expect(calculateSaltDosing({ ...DEFAULT_SALT_DOSING_INPUT, volumeLitres: 0 })).toEqual({ ok: false, error: 'volume' });
+    expect(calculateSaltDosing({ ...DEFAULT_SALT_DOSING_INPUT, targetSalinityPpt: Number.NaN })).toEqual({ ok: false, error: 'salinity' });
+    expect(calculateSaltDosing({ ...DEFAULT_SALT_DOSING_INPUT, productRateGramsPerLitre: 201 })).toEqual({ ok: false, error: 'productRate' });
+  });
+
+  it('keeps imperial conversions reversible', () => {
+    expect(gallonsToLitres(litresToGallons(20))).toBeCloseTo(20, 8);
+    expect(ouncesPerGallonToGramsPerLitre(gramsPerLitreToOuncesPerGallon(36))).toBeCloseTo(36, 8);
+  });
+});

package/src/tool/aquariumSaltDosingCalculator/logic.ts

@@ -0,0 +1,85 @@
+export type SaltDosingMode = 'prepare' | 'correct';
+export type UnitSystem = 'metric' | 'imperial';
+export type SaltDosingAction = 'prepare' | 'raise' | 'lower' | 'target';
+
+export interface SaltDosingInput {
+  mode: SaltDosingMode;
+  volumeLitres: number;
+  currentSalinityPpt: number;
+  targetSalinityPpt: number;
+  productRateGramsPerLitre: number;
+}
+
+export interface SaltDosingResult {
+  action: SaltDosingAction;
+  amountLitres: number;
+  amountGrams: number;
+  volumeLitres: number;
+  currentSalinityPpt: number;
+  targetSalinityPpt: number;
+  productRateGramsPerLitre: number;
+}
+
+export type SaltDosingError = 'volume' | 'salinity' | 'productRate';
+export type CalculationResult = { ok: true; value: SaltDosingResult } | { ok: false; error: SaltDosingError };
+
+export const DEFAULT_SALT_DOSING_INPUT: SaltDosingInput = {
+  mode: 'prepare',
+  volumeLitres: 20,
+  currentSalinityPpt: 0,
+  targetSalinityPpt: 35,
+  productRateGramsPerLitre: 36,
+};
+
+const MAX_VOLUME_LITRES = 100_000;
+const MAX_SALINITY_PPT = 60;
+const MAX_PRODUCT_RATE_GRAMS_PER_LITRE = 200;
+
+function isFiniteInRange(value: number, minimum: number, maximum: number): boolean {
+  return Number.isFinite(value) && value >= minimum && value <= maximum;
+}
+
+function validateInput(input: SaltDosingInput): SaltDosingError | null {
+  if (!isFiniteInRange(input.volumeLitres, 0.1, MAX_VOLUME_LITRES)) return 'volume';
+  if (!isFiniteInRange(input.targetSalinityPpt, 0, MAX_SALINITY_PPT) || !isFiniteInRange(input.currentSalinityPpt, 0, MAX_SALINITY_PPT)) return 'salinity';
+  if (input.mode === 'prepare' && input.targetSalinityPpt <= 0) return 'salinity';
+  if (!isFiniteInRange(input.productRateGramsPerLitre, 0.01, MAX_PRODUCT_RATE_GRAMS_PER_LITRE)) return 'productRate';
+  return null;
+}
+
+export function calculateSaltDosing(input: SaltDosingInput): CalculationResult {
+  const error = validateInput(input);
+  if (error !== null) return { ok: false, error };
+
+  if (input.mode === 'prepare') {
+    return {
+      ok: true,
+      value: {
+        action: 'prepare',
+        amountLitres: input.volumeLitres,
+        amountGrams: input.volumeLitres * input.productRateGramsPerLitre,
+        volumeLitres: input.volumeLitres,
+        currentSalinityPpt: 0,
+        targetSalinityPpt: input.targetSalinityPpt,
+        productRateGramsPerLitre: input.productRateGramsPerLitre,
+      },
+    };
+  }
+
+  const difference = input.targetSalinityPpt - input.currentSalinityPpt;
+  if (difference === 0) {
+    return { ok: true, value: { action: 'target', amountLitres: 0, amountGrams: 0, ...input } };
+  }
+  if (difference > 0) {
+    const amountGrams = input.volumeLitres * (difference / input.targetSalinityPpt) * input.productRateGramsPerLitre;
+    return { ok: true, value: { action: 'raise', amountLitres: 0, amountGrams, ...input } };
+  }
+
+  const amountLitres = input.volumeLitres * (Math.abs(difference) / input.currentSalinityPpt);
+  return { ok: true, value: { action: 'lower', amountLitres, amountGrams: 0, ...input } };
+}
+
+export function litresToGallons(litres: number): number { return litres / 3.785411784; }
+export function gallonsToLitres(gallons: number): number { return gallons * 3.785411784; }
+export function gramsPerLitreToOuncesPerGallon(gramsPerLitre: number): number { return gramsPerLitre * 0.133526471; }
+export function ouncesPerGallonToGramsPerLitre(ouncesPerGallon: number): number { return ouncesPerGallon / 0.133526471; }

package/src/tool/aquariumSaltDosingCalculator/seo.astro

@@ -0,0 +1,11 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { aquariumSaltDosingCalculator } from './entry';
+import type { KnownLocale } from '../../types';
+
+const { locale = 'en' } = Astro.props as { locale?: KnownLocale };
+const loader = aquariumSaltDosingCalculator.i18n[locale] ?? aquariumSaltDosingCalculator.i18n.en;
+const content = loader === undefined ? undefined : await loader();
+---
+
+{content && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/aquariumSaltDosingCalculator/storage.ts

@@ -0,0 +1,19 @@
+import { DEFAULT_SALT_DOSING_INPUT, type SaltDosingInput, type UnitSystem } from './logic';
+
+const STORAGE_KEY = 'jjlmoya-utils-aquarium:salt-dosing';
+
+export interface SavedSaltDosingState { unit: UnitSystem; input: SaltDosingInput; }
+
+export function defaultSaltDosingState(): SavedSaltDosingState { return { unit: 'metric', input: { ...DEFAULT_SALT_DOSING_INPUT } }; }
+
+export function loadSaltDosingState(): SavedSaltDosingState | null {
+  try {
+    const value = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? 'null') as SavedSaltDosingState | null;
+    if (!value || (value.unit !== 'metric' && value.unit !== 'imperial') || !value.input) return null;
+    return value;
+  } catch { return null; }
+}
+
+export function saveSaltDosingState(state: SavedSaltDosingState): void {
+  try { localStorage.setItem(STORAGE_KEY, JSON.stringify(state)); } catch {}
+}

package/src/tool/aquariumSaltDosingCalculator/ui.ts

@@ -0,0 +1,47 @@
+export interface AquariumSaltDosingCalculatorUI {
+  [key: string]: string;
+  toolKicker: string;
+  resultTitle: string;
+  configureTitle: string;
+  modeLabel: string;
+  prepareMode: string;
+  correctMode: string;
+  unitsLabel: string;
+  metricLabel: string;
+  imperialLabel: string;
+  volumeLabel: string;
+  currentSalinityLabel: string;
+  targetSalinityLabel: string;
+  productRateLabel: string;
+  salinityUnit: string;
+  metricVolumeUnit: string;
+  imperialVolumeUnit: string;
+  metricRateUnit: string;
+  imperialRateUnit: string;
+  presetLabel: string;
+  brackishPreset: string;
+  marinePreset: string;
+  customPreset: string;
+  prepareHint: string;
+  correctHint: string;
+  productRateHint: string;
+  outputActionLabel: string;
+  prepareAction: string;
+  raiseAction: string;
+  lowerAction: string;
+  targetAction: string;
+  amountLabel: string;
+  saltAmountLabel: string;
+  waterAmountLabel: string;
+  noChangeLabel: string;
+  currentTargetLabel: string;
+  verificationNote: string;
+  gradualNote: string;
+  emptyState: string;
+  invalidState: string;
+  resetLabel: string;
+  gramsUnit: string;
+  ouncesUnit: string;
+  litresUnit: string;
+  gallonsUnit: string;
+}

package/src/tools.ts

@@ -3,6 +3,7 @@ import { aquariumTankVolumeWaterChangeCalculator } from './tool/aquariumTankVolu
 import { aquariumFilterTurnoverStockingPlanner } from './tool/aquariumFilterTurnoverStockingPlanner/entry';
 import { aquariumLightingPhotoperiodPlanner } from './tool/aquariumLightingPhotoperiodPlanner/entry';
 import { aquariumEvaporationTopOffPlanner } from './tool/aquariumEvaporationTopOffPlanner/entry';
+import { aquariumSaltDosingCalculator } from './tool/aquariumSaltDosingCalculator/entry';
 
 export const ALL_TOOLS = [{
   entry: aquariumTankVolumeWaterChangeCalculator,
@@ -24,4 +25,9 @@ export const ALL_TOOLS = [{
   Component: () => import('./tool/aquariumEvaporationTopOffPlanner/component.astro'),
   SEOComponent: () => import('./tool/aquariumEvaporationTopOffPlanner/seo.astro'),
   BibliographyComponent: () => import('./tool/aquariumEvaporationTopOffPlanner/bibliography.astro'),
+}, {
+  entry: aquariumSaltDosingCalculator,
+  Component: () => import('./tool/aquariumSaltDosingCalculator/component.astro'),
+  SEOComponent: () => import('./tool/aquariumSaltDosingCalculator/seo.astro'),
+  BibliographyComponent: () => import('./tool/aquariumSaltDosingCalculator/bibliography.astro'),
 }];