@recipe-scope/quantity-parser 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+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,95 @@
+# @recipe-scope/quantity-parser
+
+Zero-dependency Japanese quantity string parser for recipe ingredients.
+
+## Installation
+
+```bash
+npm install @recipe-scope/quantity-parser
+```
+
+## Usage
+
+### Basic Parsing
+
+```typescript
+import { QuantityParser } from '@recipe-scope/quantity-parser';
+
+// Simple quantities
+QuantityParser.parse('100g');      // { value: 100, unit: 'g' }
+QuantityParser.parse('大さじ1');    // { value: 1, unit: '大さじ' }
+QuantityParser.parse('1/2カップ');  // { value: 0.5, unit: 'カップ' }
+
+// Full-width numbers
+QuantityParser.parse('３個');       // { value: 3, unit: '個' }
+
+// Fractions
+QuantityParser.parse('1と1/2カップ'); // { value: 1.5, unit: 'カップ' }
+QuantityParser.parse('半個');        // { value: 0.5, unit: '個' }
+
+// Ranges (uses minimum value)
+QuantityParser.parse('1~2本');      // { value: 1, unit: '本' }
+
+// Parentheses (extracts grams/ml)
+QuantityParser.parse('なす(100g)'); // { value: 100, unit: 'g' }
+
+// Tube measurements
+QuantityParser.parse('チューブ3cm'); // { value: 3, unit: 'チューブcm' }
+```
+
+### Formatting
+
+```typescript
+import { QuantityFormatter } from '@recipe-scope/quantity-parser';
+
+// Basic formatting
+QuantityFormatter.format(100, 'g');    // '100 g'
+QuantityFormatter.format(2, '個');      // '2 個'
+
+// Spoon fractions
+QuantityFormatter.format(1.5, '大さじ'); // '大さじ 1と1/2'
+QuantityFormatter.format(0.5, '小さじ'); // '小さじ 1/2'
+
+// Tube measurements
+QuantityFormatter.format(3, 'チューブcm'); // 'チューブ3cm'
+
+// Size prefixes
+QuantityFormatter.format(2, '小個');    // '小2個'
+
+// Ambiguous units
+QuantityFormatter.format(0, '少々');    // '少々'
+QuantityFormatter.format(0, '適量');    // '適量'
+```
+
+### Configuration
+
+Access unit configuration for custom calculations:
+
+```typescript
+import { UNITS_CONFIG } from '@recipe-scope/quantity-parser';
+
+// Standard volumes in ml
+UNITS_CONFIG.STANDARD_VOLUME_ML['大さじ']; // 15
+UNITS_CONFIG.STANDARD_VOLUME_ML['小さじ']; // 5
+UNITS_CONFIG.STANDARD_VOLUME_ML['カップ']; // 200
+
+// Countable unit aliases
+UNITS_CONFIG.UNIT_SINGLE_ALIASES; // ['個', '本', '匹', '尾', '玉', '粒', '株']
+
+// Ambiguous units
+UNITS_CONFIG.AMBIGUOUS; // ['少々', '適量', 'ひとつまみ', '適宜', 'ひとつかみ']
+```
+
+## Features
+
+- **Zero dependencies** - Pure TypeScript implementation
+- **Full-width support** - Handles both half-width and full-width numbers
+- **Fraction parsing** - Supports various fraction formats (1/2, 半, 1と1/2, 8分の1)
+- **Range handling** - Extracts minimum value from ranges (1~2個 → 1)
+- **Parentheses extraction** - Prioritizes gram/ml values in parentheses
+- **Unit normalization** - Normalizes units (cc → ml, コ → 個)
+- **Preprocessing** - Removes cutting instructions (みじん切り, 乱切り, etc.)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,181 @@
+/**
+ * Result of parsing a single value and unit from a strategy.
+ */
+interface ParsedResult {
+    value: number;
+    unit: string;
+}
+/**
+ * Options for parsing quantities.
+ */
+interface ParseOptions {
+    /**
+     * How to handle range values (e.g. "1~2").
+     * - 'min': Use the minimum value (default behavior in v1)
+     * - 'max': Use the maximum value
+     * - 'mean': Use the average/mean value
+     * @default 'min'
+     */
+    rangeMode?: 'min' | 'max' | 'mean';
+}
+/**
+ * Interface for parsing strategies.
+ */
+interface ParseStrategy {
+    /**
+     * Attempts to parse the quantity string.
+     * Returns null if the strategy does not apply.
+     */
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+/**
+ * Result of parsing a quantity string.
+ */
+interface ParsedQuantityResult {
+    /** Numeric value extracted from the quantity string */
+    value: number;
+    /** Normalized unit string */
+    unit: string;
+    /** The preprocessed/normalized quantity string */
+    normalizedQuantity?: string;
+}
+
+/**
+ * Parses Japanese quantity strings into numeric values and normalized units.
+ *
+ * @example
+ * ```typescript
+ * QuantityParser.parse('大さじ1'); // { value: 1, unit: '大さじ' }
+ * QuantityParser.parse('1/2カップ'); // { value: 0.5, unit: 'カップ' }
+ * QuantityParser.parse('100g'); // { value: 100, unit: 'g' }
+ * ```
+ */
+declare class QuantityParser {
+    private static strategies;
+    /**
+     * Parses a quantity string into a numeric value and a normalized unit.
+     * @param quantityStr - The quantity string to parse (e.g., "大さじ1", "100g", "1/2カップ")
+     * @param options - Parsing options (e.g. rangeMode)
+     * @returns Parsed result with value, unit, and normalized quantity string
+     */
+    static parse(quantityStr: string, options?: ParseOptions): ParsedQuantityResult;
+    private static preprocess;
+    private static postprocessUnit;
+}
+
+/**
+ * Formats quantity values with units for display.
+ *
+ * @example
+ * ```typescript
+ * QuantityFormatter.format(1.5, '大さじ'); // '大さじ 1と1/2'
+ * QuantityFormatter.format(100, 'g'); // '100 g'
+ * QuantityFormatter.format(3, 'チューブcm'); // 'チューブ3cm'
+ * ```
+ */
+declare class QuantityFormatter {
+    /**
+     * Formats a numeric value with its unit for display.
+     * @param value - The numeric value
+     * @param unit - The unit string
+     * @returns Formatted string for display
+     */
+    static format(value: number, unit: string): string;
+    private static formatSpoon;
+}
+
+/**
+ * Unit definitions and measurement mappings for quantity parsing.
+ */
+declare const UNITS_CONFIG: {
+    /**
+     * Standard volume mapping in Milliliters (ml).
+     * Used for density calculations.
+     */
+    readonly STANDARD_VOLUME_ML: {
+        readonly カップ: 200;
+        readonly 大さじ: 15;
+        readonly 小さじ: 5;
+        readonly ml: 1;
+        readonly cc: 1;
+        readonly ミリリットル: 1;
+        readonly L: 1000;
+        readonly リットル: 1000;
+        readonly 少々: 0.8;
+        readonly ひとつまみ: 1;
+        readonly 合: 180;
+        readonly 小: 5;
+        readonly 大: 15;
+        readonly 適量: 0;
+        readonly 適宜: 0;
+    };
+    /**
+     * Units that represent a "single entity" of a countable food.
+     * If a food has any of these in unitWeights, they can be treated as interchangeable
+     * fallbacks (1 entity = unitWeight).
+     */
+    readonly UNIT_SINGLE_ALIASES: readonly ["個", "本", "匹", "尾", "玉", "粒", "株"];
+    /**
+     * Ambiguous measurement expressions.
+     */
+    readonly AMBIGUOUS: readonly ["少々", "適量", "ひとつまみ", "適宜", "ひとつかみ"];
+    /**
+     * Special units with fixed weights or behaviors.
+     */
+    readonly SPECIAL_FIXED: readonly ["少々", "ひとつまみ"];
+};
+type StandardVolumeUnit = keyof typeof UNITS_CONFIG.STANDARD_VOLUME_ML;
+type UnitSingleAlias = (typeof UNITS_CONFIG.UNIT_SINGLE_ALIASES)[number];
+type AmbiguousUnit = (typeof UNITS_CONFIG.AMBIGUOUS)[number];
+type SpecialFixedUnit = (typeof UNITS_CONFIG.SPECIAL_FIXED)[number];
+
+/**
+ * Parses tube measurements like "チューブ3cm" or "チューブで2センチ".
+ */
+declare class TubeStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+/**
+ * Parses grams or milliliters in parentheses like "(100g)" or "(200ml)".
+ */
+declare class GramsInParensStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+/**
+ * Parses range expressions like "1~2個".
+ * Behavior depends on options.rangeMode (default: min).
+ */
+declare class RangeStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+/**
+ * Parses various fraction formats:
+ * - Mixed fractions: "1と1/2", "1・1/2"
+ * - Half: "1/2", "半"
+ * - Simple fractions: "1/4"
+ * - Japanese fractions: "8分の1"
+ */
+declare class FractionStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+/**
+ * Parses unit prefix patterns like "大さじ1", "小1", "大1/2", "カップ1".
+ */
+declare class UnitPrefixStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+/**
+ * Fallback strategy for parsing:
+ * - Explicit grams/ml trailing patterns
+ * - General number + suffix patterns
+ */
+declare class SuffixStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+export { type AmbiguousUnit, FractionStrategy, GramsInParensStrategy, type ParseOptions, type ParseStrategy, type ParsedQuantityResult, type ParsedResult, QuantityFormatter, QuantityParser, RangeStrategy, type SpecialFixedUnit, type StandardVolumeUnit, SuffixStrategy, TubeStrategy, UNITS_CONFIG, UnitPrefixStrategy, type UnitSingleAlias };

package/dist/index.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Result of parsing a single value and unit from a strategy.
+ */
+interface ParsedResult {
+    value: number;
+    unit: string;
+}
+/**
+ * Options for parsing quantities.
+ */
+interface ParseOptions {
+    /**
+     * How to handle range values (e.g. "1~2").
+     * - 'min': Use the minimum value (default behavior in v1)
+     * - 'max': Use the maximum value
+     * - 'mean': Use the average/mean value
+     * @default 'min'
+     */
+    rangeMode?: 'min' | 'max' | 'mean';
+}
+/**
+ * Interface for parsing strategies.
+ */
+interface ParseStrategy {
+    /**
+     * Attempts to parse the quantity string.
+     * Returns null if the strategy does not apply.
+     */
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+/**
+ * Result of parsing a quantity string.
+ */
+interface ParsedQuantityResult {
+    /** Numeric value extracted from the quantity string */
+    value: number;
+    /** Normalized unit string */
+    unit: string;
+    /** The preprocessed/normalized quantity string */
+    normalizedQuantity?: string;
+}
+
+/**
+ * Parses Japanese quantity strings into numeric values and normalized units.
+ *
+ * @example
+ * ```typescript
+ * QuantityParser.parse('大さじ1'); // { value: 1, unit: '大さじ' }
+ * QuantityParser.parse('1/2カップ'); // { value: 0.5, unit: 'カップ' }
+ * QuantityParser.parse('100g'); // { value: 100, unit: 'g' }
+ * ```
+ */
+declare class QuantityParser {
+    private static strategies;
+    /**
+     * Parses a quantity string into a numeric value and a normalized unit.
+     * @param quantityStr - The quantity string to parse (e.g., "大さじ1", "100g", "1/2カップ")
+     * @param options - Parsing options (e.g. rangeMode)
+     * @returns Parsed result with value, unit, and normalized quantity string
+     */
+    static parse(quantityStr: string, options?: ParseOptions): ParsedQuantityResult;
+    private static preprocess;
+    private static postprocessUnit;
+}
+
+/**
+ * Formats quantity values with units for display.
+ *
+ * @example
+ * ```typescript
+ * QuantityFormatter.format(1.5, '大さじ'); // '大さじ 1と1/2'
+ * QuantityFormatter.format(100, 'g'); // '100 g'
+ * QuantityFormatter.format(3, 'チューブcm'); // 'チューブ3cm'
+ * ```
+ */
+declare class QuantityFormatter {
+    /**
+     * Formats a numeric value with its unit for display.
+     * @param value - The numeric value
+     * @param unit - The unit string
+     * @returns Formatted string for display
+     */
+    static format(value: number, unit: string): string;
+    private static formatSpoon;
+}
+
+/**
+ * Unit definitions and measurement mappings for quantity parsing.
+ */
+declare const UNITS_CONFIG: {
+    /**
+     * Standard volume mapping in Milliliters (ml).
+     * Used for density calculations.
+     */
+    readonly STANDARD_VOLUME_ML: {
+        readonly カップ: 200;
+        readonly 大さじ: 15;
+        readonly 小さじ: 5;
+        readonly ml: 1;
+        readonly cc: 1;
+        readonly ミリリットル: 1;
+        readonly L: 1000;
+        readonly リットル: 1000;
+        readonly 少々: 0.8;
+        readonly ひとつまみ: 1;
+        readonly 合: 180;
+        readonly 小: 5;
+        readonly 大: 15;
+        readonly 適量: 0;
+        readonly 適宜: 0;
+    };
+    /**
+     * Units that represent a "single entity" of a countable food.
+     * If a food has any of these in unitWeights, they can be treated as interchangeable
+     * fallbacks (1 entity = unitWeight).
+     */
+    readonly UNIT_SINGLE_ALIASES: readonly ["個", "本", "匹", "尾", "玉", "粒", "株"];
+    /**
+     * Ambiguous measurement expressions.
+     */
+    readonly AMBIGUOUS: readonly ["少々", "適量", "ひとつまみ", "適宜", "ひとつかみ"];
+    /**
+     * Special units with fixed weights or behaviors.
+     */
+    readonly SPECIAL_FIXED: readonly ["少々", "ひとつまみ"];
+};
+type StandardVolumeUnit = keyof typeof UNITS_CONFIG.STANDARD_VOLUME_ML;
+type UnitSingleAlias = (typeof UNITS_CONFIG.UNIT_SINGLE_ALIASES)[number];
+type AmbiguousUnit = (typeof UNITS_CONFIG.AMBIGUOUS)[number];
+type SpecialFixedUnit = (typeof UNITS_CONFIG.SPECIAL_FIXED)[number];
+
+/**
+ * Parses tube measurements like "チューブ3cm" or "チューブで2センチ".
+ */
+declare class TubeStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+/**
+ * Parses grams or milliliters in parentheses like "(100g)" or "(200ml)".
+ */
+declare class GramsInParensStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+/**
+ * Parses range expressions like "1~2個".
+ * Behavior depends on options.rangeMode (default: min).
+ */
+declare class RangeStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+/**
+ * Parses various fraction formats:
+ * - Mixed fractions: "1と1/2", "1・1/2"
+ * - Half: "1/2", "半"
+ * - Simple fractions: "1/4"
+ * - Japanese fractions: "8分の1"
+ */
+declare class FractionStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+/**
+ * Parses unit prefix patterns like "大さじ1", "小1", "大1/2", "カップ1".
+ */
+declare class UnitPrefixStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+/**
+ * Fallback strategy for parsing:
+ * - Explicit grams/ml trailing patterns
+ * - General number + suffix patterns
+ */
+declare class SuffixStrategy implements ParseStrategy {
+    parse(quantity: string, options?: ParseOptions): ParsedResult | null;
+}
+
+export { type AmbiguousUnit, FractionStrategy, GramsInParensStrategy, type ParseOptions, type ParseStrategy, type ParsedQuantityResult, type ParsedResult, QuantityFormatter, QuantityParser, RangeStrategy, type SpecialFixedUnit, type StandardVolumeUnit, SuffixStrategy, TubeStrategy, UNITS_CONFIG, UnitPrefixStrategy, type UnitSingleAlias };