@othree.io/cerillo 0.1.0 → 2.0.0

package/.gitlab-ci.yml

@@ -1,14 +1,15 @@
-image: node:12-alpine
+image: node:20
 
 cache:
   key: ${CI_PIPELINE_ID}
   paths:
     - node_modules/
+    - lib/
 
 build:
   stage: build
   script:
-    - npm install
+    - npm install && npm run build
 
 test:
   stage: test
@@ -17,9 +18,11 @@ test:
 
 deploy:
   stage: deploy
+  variables:
+    NPM_CONFIG_USERCONFIG: '$CI_PROJECT_DIR/.npmrc'
   script:
     - cat $NPM > .npmrc
-    - npm publish --access public
+    - npx semantic-release
   only:
     refs:
-      - master
+      - master

package/README.md

@@ -1,2 +1,110 @@
 # cerillo
 
+A lightweight, lazy, and fully typed pattern-matching library for TypeScript. Matches are built as chainable expressions and only evaluated when you call `get`.
+
+## Install
+
+```bash
+npm install @othree.io/cerillo
+```
+
+Peer dependency: [`@othree.io/optional`](https://www.npmjs.com/package/@othree.io/optional) ^2.3.3
+
+## Usage
+
+### Literal matching with `is`
+
+```typescript
+import { match } from '@othree.io/cerillo'
+
+const result = match<string, string>('hello')
+    .is('hello').then(_ => 'Hi there!')
+    .is('bye').then(_ => 'Goodbye!')
+    .get()
+
+result.get() // 'Hi there!'
+```
+
+`is` accepts multiple values:
+
+```typescript
+const result = match<string, string>('b')
+    .is('a', 'b', 'c').then(_ => 'Matched!')
+    .getOrThrow() // 'Matched!'
+```
+
+### Conditional matching with `when`
+
+```typescript
+const result = match<number, string>(42)
+    .when(n => n > 100).then(_ => 'big')
+    .when(n => n > 0).then(_ => 'positive')
+    .otherwise(_ => 'non-positive')
+    .getOrThrow() // 'positive'
+```
+
+### Type narrowing
+
+`when` supports type-guard callbacks, narrowing the type in the `then` branch:
+
+```typescript
+type Shape =
+    | { kind: 'circle'; radius: number }
+    | { kind: 'rectangle'; width: number; height: number }
+
+const isCircle = (s: Shape): s is { kind: 'circle'; radius: number } =>
+    s.kind === 'circle'
+
+const area = match<Shape, number>(shape)
+    .when(isCircle).then(c => Math.PI * c.radius ** 2)   // c is narrowed
+    .when(isRectangle).then(r => r.width * r.height)      // r is narrowed
+    .getOrThrow()
+```
+
+### Default / otherwise
+
+Provide a fallback with `default` or its alias `otherwise`:
+
+```typescript
+match<string, string>('unknown')
+    .is('a').then(_ => 'A')
+    .default(_ => 'fallback')
+    .getOrThrow() // 'fallback'
+```
+
+### Async matching
+
+When `then` callbacks return promises, use `getAsync` or `getAsyncOrThrow`:
+
+```typescript
+const result = await match<string, Promise<string>>('hello')
+    .is('hello').then(async _ => fetchGreeting())
+    .getAsyncOrThrow() // resolves to the greeting
+```
+
+## API
+
+### `match<A, B>(value: A): Match<A, B>`
+
+Creates a new match expression for `value`.
+
+### `Match<A, B>`
+
+| Method | Returns | Description |
+|---|---|---|
+| `.is(...expected)` | `{ then }` | Match against one or more literal values |
+| `.when(callback)` | `{ then }` | Match when callback returns `true` (supports type guards) |
+| `.default(callback)` | `Match<A, B>` | Set a fallback handler |
+| `.otherwise(callback)` | `Match<A, B>` | Alias for `default` |
+| `.get()` | `Optional<B>` | Evaluate and return the result wrapped in `Optional` |
+| `.getOrThrow()` | `B` | Evaluate and return the result, throws `MatchError` on no match |
+| `.getAsync()` | `Promise<Optional<Awaited<B>>>` | Evaluate async and return the result wrapped in `Optional` |
+| `.getAsyncOrThrow()` | `Promise<Awaited<B>>` | Evaluate async, rejects with `MatchError` on no match |
+
+### `MatchError`
+
+Thrown (or used as the `Optional` error) when no pattern matches and no default is defined.
+
+## License
+
+ISC

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { match, Match, MatchFn, MatchError } from './match';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA"}

package/lib/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MatchError = exports.match = void 0;
+var match_1 = require("./match");
+Object.defineProperty(exports, "match", { enumerable: true, get: function () { return match_1.match; } });
+Object.defineProperty(exports, "MatchError", { enumerable: true, get: function () { return match_1.MatchError; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iCAA2D;AAAlD,8FAAA,KAAK,OAAA;AAAkB,mGAAA,UAAU,OAAA"}

package/lib/match.d.ts

@@ -0,0 +1,29 @@
+import { Optional } from '@othree.io/optional';
+type ThenCallback<A, B> = (value: A) => B;
+type WhenCallback<A> = (value: A) => boolean;
+export declare class MatchError extends Error {
+    constructor(message: string);
+}
+export type Match<A, B> = Readonly<{
+    get: () => Optional<B>;
+    getOrThrow: () => B;
+    getAsync: () => Promise<Optional<Awaited<B>>>;
+    getAsyncOrThrow: () => Promise<Awaited<B>>;
+    is: (...expected: ReadonlyArray<A>) => Readonly<{
+        then: (callback: ThenCallback<A, B>) => Match<A, B>;
+    }>;
+    when: {
+        <S extends A>(callback: (value: A) => value is S): Readonly<{
+            then: (callback: (value: S) => B) => Match<A, B>;
+        }>;
+        (callback: WhenCallback<A>): Readonly<{
+            then: (callback: ThenCallback<A, B>) => Match<A, B>;
+        }>;
+    };
+    default: (callback: ThenCallback<A, B>) => Match<A, B>;
+    otherwise: (callback: ThenCallback<A, B>) => Match<A, B>;
+}>;
+export type MatchFn = <A, B>(value: A) => Match<A, B>;
+export declare const match: MatchFn;
+export {};
+//# sourceMappingURL=match.d.ts.map

package/lib/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../src/match.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAS,MAAM,qBAAqB,CAAA;AAErD,KAAK,YAAY,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAA;AACzC,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAA;AAE5C,qBAAa,UAAW,SAAQ,KAAK;gBACrB,OAAO,EAAE,MAAM;CAU9B;AAOD,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC;IAC/B,GAAG,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAA;IACtB,UAAU,EAAE,MAAM,CAAC,CAAA;IACnB,QAAQ,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7C,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1C,EAAE,EAAE,CAAC,GAAG,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC;QAC5C,IAAI,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;KACtD,CAAC,CAAA;IACF,IAAI,EAAE;QACF,CAAC,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC;YACxD,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;SACnD,CAAC,CAAA;QACF,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC;YAClC,IAAI,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;SACtD,CAAC,CAAA;KACL,CAAA;IACD,OAAO,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACtD,SAAS,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;CAC3D,CAAC,CAAA;AAEF,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AA+CrD,eAAO,MAAM,KAAK,EAAE,OACuB,CAAA"}

package/lib/match.js

@@ -0,0 +1,59 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.match = exports.MatchError = void 0;
+const optional_1 = require("@othree.io/optional");
+class MatchError extends Error {
+    constructor(message) {
+        super(message);
+        const ErrorWithCapture = Error;
+        if (ErrorWithCapture.captureStackTrace) {
+            ErrorWithCapture.captureStackTrace(this, MatchError);
+        }
+        this.name = 'MatchError';
+    }
+}
+exports.MatchError = MatchError;
+const createMatch = (value, patterns, defaultCallback) => {
+    const get = () => (0, optional_1.Optional)(patterns.find(p => p.when(value)))
+        .map(pattern => pattern.then(value))
+        .orMap(() => (0, optional_1.Optional)(defaultCallback).map(cb => cb(value)))
+        .orMap(() => (0, optional_1.Empty)(new MatchError(`Nothing matched for value: ${value}`)));
+    const getAsync = () => (0, optional_1.Optional)(patterns.find(p => p.when(value)))
+        .map(pattern => pattern.then)
+        .orMap(() => (0, optional_1.Optional)(defaultCallback))
+        .mapAsync((cb) => __awaiter(void 0, void 0, void 0, function* () { return yield cb(value); }))
+        .then(opt => opt.orMap(() => (0, optional_1.Empty)(new MatchError(`Nothing matched for value: ${value}`))));
+    const defaultFn = (callback) => createMatch(value, patterns, callback);
+    return {
+        get,
+        getOrThrow: () => get().get(),
+        getAsync,
+        getAsyncOrThrow: () => getAsync().then(opt => opt.get()),
+        is: (...expected) => ({
+            then: (thenCallback) => createMatch(value, patterns.concat([{
+                    when: (v) => expected.some(e => e === v),
+                    then: thenCallback
+                }]), defaultCallback)
+        }),
+        when: (validationCallback) => ({
+            then: (thenCallback) => createMatch(value, patterns.concat([{
+                    when: validationCallback,
+                    then: thenCallback
+                }]), defaultCallback)
+        }),
+        default: defaultFn,
+        otherwise: defaultFn
+    };
+};
+const match = (value) => createMatch(value, [], undefined);
+exports.match = match;
+//# sourceMappingURL=match.js.map

package/lib/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../src/match.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "@othree.io/cerillo",
-  "version": "0.1.0",
+  "version": "2.0.0",
   "description": "Matching library",
-  "main": "index.js",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js"
+    }
+  },
   "scripts": {
-    "test": "jest"
+    "test": "vitest run --coverage",
+    "build": "tsc"
   },
   "repository": {
     "type": "git",
@@ -21,7 +30,13 @@
     "url": "https://gitlab.com/othree.oss/cerillo/issues"
   },
   "homepage": "https://gitlab.com/othree.oss/cerillo#readme",
+  "peerDependencies": {
+    "@othree.io/optional": "^2.3.3"
+  },
   "devDependencies": {
-    "jest": "^26.5.3"
+    "@othree.io/optional": "^2.3.3",
+    "@vitest/coverage-v8": "^3.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
   }
 }

package/release.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+    plugins: ['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm'],
+    branches: ['master', 'main']
+}

package/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+    test: {
+        coverage: {
+            provider: 'v8',
+            reporter: ['text', 'json', 'html'],
+            all: true,
+            include: ['src/**/*.ts'],
+            thresholds: {
+                lines: 100,
+                functions: 100,
+                branches: 100,
+                statements: 100
+            }
+        }
+    }
+})

package/index.js

@@ -1,3 +0,0 @@
-const {match} = require('./src/match')
-
-module.exports = {match}

package/src/match.js

@@ -1,46 +0,0 @@
-function unboundMatch(value) {
-    const patterns = []
-    let def = undefined
-
-    const when = function (validationCallback) {
-        const then = function (thenCallback) {
-            patterns.push({
-                when: validationCallback,
-                then: thenCallback
-            })
-            return this
-        }.bind(this)
-
-        return {
-            then
-        }
-    }
-    const defaultMatch = function(callback) {
-        def = callback
-
-        return this
-    }
-
-    const response = {
-        get: () => {
-            const pattern = patterns.find(pattern => pattern.when(value))
-            if (pattern) {
-                return pattern.then(value)
-            } else {
-                if (def) {
-                    return def(value)
-                } else {
-                    throw new Error(`Nothing matched for value: ${value}`)
-                }
-            }
-        }
-    }
-
-    response.when = when.bind(response)
-    response.default = defaultMatch.bind(response)
-    return response
-}
-
-const match = unboundMatch.bind(unboundMatch)
-
-module.exports = { match }

package/test/match.test.js

@@ -1,42 +0,0 @@
-const {match} = require('../src/match')
-
-describe('match', () => {
-
-    const expectations = [
-        {
-            value: 'bye',
-            expectation: 'MEANT TO SAY GOODBYE'
-        },
-        {
-            value: 'hello',
-            expectation: 'HELLO'
-        },
-        {
-            value: 'unexpected',
-            expectation: 'DEFAULT VALUE'
-        }
-    ]
-
-    expectations.forEach(expectation => {
-        it(`should match ${expectation.value} and return the expected value`, () => {
-
-            const result = match(expectation.value)
-                .when(_ => _ === 'bye').then(_ => 'MEANT TO SAY GOODBYE')
-                .when(_ => _ === 'hello').then(_ => _.toUpperCase())
-                .default(_ => 'DEFAULT VALUE')
-                .get()
-
-            expect(result).toStrictEqual(expectation.expectation)
-        })
-    })
-
-    it('throw an error if there is no match and no default defined', () => {
-        const value = 'unexpected'
-        const lazyMatch = match(value)
-            .when(_ => _ === 'bye').then(_ => 'MEANT TO SAY GOODBYE')
-            .when(_ => _ === 'hello').then(_ => _.toUpperCase())
-
-        expect(() => lazyMatch.get()).toThrow(`Nothing matched for value: ${value}`)
-    })
-
-})