devstack 0.1.0

package/vendor/skills/skills/effect-ts/references/schema-transforms-and-filters.md

@@ -0,0 +1,293 @@
+# Schema Transformations and Filters
+
+Schema transformations for converting between types, filters for custom validation, and built-in refinements.
+
+## Table of Contents
+
+- [Schema.transform](#schematransform)
+- [Schema.transformOrFail](#schematransformorfail)
+- [Built-in Filters (Refinements)](#built-in-filters)
+- [Custom Filters with Schema.filter](#custom-filters)
+- [Composing Schemas](#composing-schemas)
+
+## Schema.transform
+
+Create a new schema that converts data between a source and target schema. Use when the transformation always succeeds:
+
+```typescript
+import * as Schema from "effect/Schema";
+
+// Convert "on"/"off" to boolean
+const BooleanFromString = Schema.transform(
+  Schema.Literal("on", "off"), // Source: "on" | "off"
+  Schema.Boolean, // Target: boolean
+  {
+    strict: true,
+    decode: literal => literal === "on",
+    encode: bool => (bool ? "on" : "off"),
+  }
+);
+// Schema<boolean, "on" | "off">
+
+Schema.decodeUnknownSync(BooleanFromString)("on"); // true
+Schema.encodeSync(BooleanFromString)(false); // "off"
+```
+
+### Array to Set
+
+```typescript
+const ReadonlySetFromArray = <A, I, R>(
+  itemSchema: Schema.Schema<A, I, R>
+): Schema.Schema<ReadonlySet<A>, ReadonlyArray<I>, R> =>
+  Schema.transform(
+    Schema.Array(itemSchema),
+    Schema.ReadonlySetFromSelf(Schema.typeSchema(itemSchema)),
+    {
+      strict: true,
+      decode: items => new Set(items),
+      encode: set => Array.from(set.values()),
+    }
+  );
+```
+
+### Composing Transformations
+
+You can compose transformation schemas (source and/or target are themselves transformations):
+
+```typescript
+// NumberFromString: string -> number
+// BooleanFromString: "on"|"off" -> boolean
+// Composed: string -> boolean
+const BooleanFromNumericString = Schema.transform(
+  Schema.NumberFromString, // string -> number
+  BooleanFromString, // "on"|"off" -> boolean
+  {
+    strict: true,
+    decode: n => (n > 0 ? "on" : "off"),
+    encode: s => (s === "on" ? 1 : -1),
+  }
+);
+
+Schema.decodeUnknownSync(BooleanFromNumericString)("100"); // true
+```
+
+### Non-strict Mode
+
+Use `strict: false` when types don't exactly align but the transformation is correct:
+
+```typescript
+const Clamped = (min: number, max: number) =>
+  Schema.transform(Schema.Number, Schema.Number, {
+    strict: false,
+    decode: n => Math.min(Math.max(n, min), max),
+    encode: n => n,
+  });
+```
+
+## Schema.transformOrFail
+
+Like `transform` but `decode`/`encode` return `Effect`, allowing failures:
+
+```typescript
+import * as Effect from "effect/Effect";
+import * as ParseResult from "effect/ParseResult";
+
+const StringToNumber = Schema.transformOrFail(Schema.String, Schema.Number, {
+  strict: true,
+  decode: (s, _, ast) => {
+    const n = Number(s);
+    return Number.isNaN(n)
+      ? ParseResult.fail(new ParseResult.Type(ast, s, "Not a number"))
+      : ParseResult.succeed(n);
+  },
+  encode: n => ParseResult.succeed(String(n)),
+});
+```
+
+### Async Transformations
+
+`transformOrFail` supports async decode/encode:
+
+```typescript
+const UsernameFromId = Schema.transformOrFail(Schema.String, Schema.String, {
+  strict: true,
+  decode: (id, _, ast) =>
+    Effect.tryPromise({
+      try: () => fetchUsername(id),
+      catch: () => new ParseResult.Type(ast, id, "Failed to fetch username"),
+    }),
+  encode: name => ParseResult.succeed(name),
+});
+```
+
+## Built-in Filters
+
+Effect provides many built-in refinement combinators. These add validation without changing the type:
+
+### String Filters
+
+```typescript
+Schema.String.pipe(Schema.minLength(1)); // Non-empty
+Schema.String.pipe(Schema.maxLength(255)); // Max length
+Schema.String.pipe(Schema.length(10)); // Exact length
+Schema.String.pipe(Schema.pattern(/^[a-z]+$/)); // Regex match
+Schema.String.pipe(Schema.startsWith("https")); // Prefix check
+Schema.String.pipe(Schema.endsWith(".com")); // Suffix check
+Schema.String.pipe(Schema.includes("@")); // Contains check
+Schema.String.pipe(Schema.trimmed()); // No leading/trailing whitespace
+Schema.String.pipe(Schema.lowercased()); // Must be lowercase
+Schema.String.pipe(Schema.uppercased()); // Must be uppercase
+Schema.NonEmptyString; // Shorthand for minLength(1)
+```
+
+### Number Filters
+
+```typescript
+Schema.Number.pipe(Schema.int()); // Integer only
+Schema.Number.pipe(Schema.positive()); // > 0
+Schema.Number.pipe(Schema.negative()); // < 0
+Schema.Number.pipe(Schema.nonPositive()); // <= 0
+Schema.Number.pipe(Schema.nonNegative()); // >= 0
+Schema.Number.pipe(Schema.between(1, 100)); // Inclusive range
+Schema.Number.pipe(Schema.greaterThan(0)); // > value
+Schema.Number.pipe(Schema.lessThan(100)); // < value
+Schema.Number.pipe(Schema.greaterThanOrEqualTo(0)); // >= value
+Schema.Number.pipe(Schema.lessThanOrEqualTo(100)); // <= value
+Schema.Number.pipe(Schema.multipleOf(5)); // Divisible by
+Schema.Int; // Shorthand for int()
+```
+
+### Array Filters
+
+```typescript
+Schema.Array(Schema.String).pipe(Schema.minItems(1)); // Non-empty array
+Schema.Array(Schema.String).pipe(Schema.maxItems(10)); // Max items
+Schema.Array(Schema.String).pipe(Schema.itemsCount(5)); // Exact count
+Schema.NonEmptyArray(Schema.String); // Shorthand
+```
+
+### Combining with Branded Types
+
+Filters compose naturally with branding:
+
+```typescript
+const Email = Schema.String.pipe(
+  Schema.pattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/),
+  Schema.brand("Email")
+);
+type Email = typeof Email.Type;
+
+const Port = Schema.Int.pipe(Schema.between(1, 65535), Schema.brand("Port"));
+type Port = typeof Port.Type;
+
+const Slug = Schema.String.pipe(
+  Schema.pattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+  Schema.maxLength(128),
+  Schema.brand("Slug")
+);
+type Slug = typeof Slug.Type;
+```
+
+## Custom Filters
+
+Use `Schema.filter` for validation logic beyond built-in filters:
+
+```typescript
+const EvenNumber = Schema.Number.pipe(Schema.filter(n => n % 2 === 0 || "must be even"));
+
+// Return type can be: true | undefined (pass), false (fail, no message),
+// string (fail with message), or ParseResult.ParseIssue
+```
+
+### Multi-field Validation with Error Paths
+
+Associate errors with specific fields in a struct:
+
+```typescript
+const PasswordForm = Schema.Struct({
+  password: Schema.String.pipe(Schema.minLength(8)),
+  confirm: Schema.String,
+}).pipe(
+  Schema.filter(form => {
+    if (form.password !== form.confirm) {
+      return {
+        path: ["confirm"],
+        issue: "Passwords must match",
+      };
+    }
+  })
+);
+```
+
+### Multiple Validation Errors
+
+Return an array to report multiple issues:
+
+```typescript
+const StrongPassword = Schema.String.pipe(
+  Schema.filter(s => {
+    const errors: string[] = [];
+    if (s.length < 8) errors.push("must be at least 8 characters");
+    if (!/[A-Z]/.test(s)) errors.push("must contain uppercase letter");
+    if (!/[0-9]/.test(s)) errors.push("must contain a digit");
+    return errors.length > 0 ? errors : undefined;
+  })
+);
+```
+
+### Annotations for JSON Schema
+
+Add metadata to custom filters for JSON Schema generation:
+
+```typescript
+const LongString = Schema.String.pipe(
+  Schema.filter(s => s.length >= 10 || "must be at least 10 characters", {
+    identifier: "LongString",
+    jsonSchema: { minLength: 10 },
+    description: "A string with at least 10 characters",
+  })
+);
+```
+
+## Composing Schemas
+
+### Schema.compose
+
+Chain two schemas where the output of the first feeds the input of the second:
+
+```typescript
+// string -> number -> positive number
+const PositiveFromString = Schema.compose(
+  Schema.NumberFromString,
+  Schema.Number.pipe(Schema.positive())
+);
+```
+
+### Schema.attachPropertySignature
+
+Add a constant property to a schema (useful for discriminated unions):
+
+```typescript
+const Circle = Schema.Struct({ radius: Schema.Number }).pipe(
+  Schema.attachPropertySignature("kind", "circle")
+);
+// Decodes: { radius: 5 } -> { kind: "circle", radius: 5 }
+// Encodes: { kind: "circle", radius: 5 } -> { radius: 5 }
+```
+
+### Common Built-in Transforms
+
+Effect provides many pre-built transformation schemas:
+
+```typescript
+Schema.NumberFromString; // string -> number
+Schema.BooleanFromString; // "true"/"false" -> boolean
+Schema.Date; // string -> Date (ISO 8601)
+Schema.DateFromSelf; // Date -> Date (validates)
+Schema.BigIntFromString; // string -> BigInt
+Schema.Trim; // string -> trimmed string
+Schema.Lowercase; // string -> lowercased string
+Schema.Uppercase; // string -> uppercased string
+Schema.split(","); // "a,b,c" -> ["a", "b", "c"]
+Schema.parseJson(innerSchema); // JSON string -> parsed + validated
+```

package/vendor/skills/skills/effect-ts/references/sink.md

@@ -0,0 +1,282 @@
+# Sink Reference
+
+Sinks consume elements from a Stream and produce a result. Comprehensive reference for creating, transforming, and composing sinks.
+
+> **See also**: [`streams-deep-dive.md`](./streams-deep-dive.md) for creating and operating on streams, [`data-types.md`](./data-types.md) for Chunk/Option used in sink results.
+
+## Table of Contents
+
+- [Type Signature](#type-signature)
+- [Running a Sink](#running-a-sink)
+- [Common Constructors](#common-constructors)
+- [Collecting](#collecting)
+- [Folding](#folding)
+- [Operations](#operations)
+- [Concurrency](#concurrency)
+- [Leftovers](#leftovers)
+- [Using Sinks with Stream.transduce](#using-sinks-with-streamtransduce)
+- [Quick Reference Table](#quick-reference-table)
+- [Import Convention](#import-convention)
+
+## Type Signature
+
+```
+     ┌─── Type of the result produced by the Sink
+     |  ┌─── Type of elements consumed by the Sink
+     |  |   ┌─── Type of any leftover elements
+     │  |   |  ┌─── Type of possible errors
+     │  │   |  |  ┌─── Type of required dependencies
+     ▼  ▼   ▼  ▼  ▼
+Sink<A, In, L, E, R>
+```
+
+- `A` — final result after consuming elements
+- `In` — element type consumed from the stream
+- `L` — leftover elements not consumed (often same as `In`)
+- `E` — error type (`never` if infallible)
+- `R` — required dependencies (`never` if none)
+
+## Running a Sink
+
+Pass a sink to `Stream.run` to consume a stream:
+
+```typescript
+import * as Stream from "effect/Stream";
+import * as Sink from "effect/Sink";
+import * as Effect from "effect/Effect";
+
+const result = yield * Stream.run(Stream.make(1, 2, 3), Sink.sum);
+// 6
+```
+
+## Common Constructors
+
+### Terminal Sinks
+
+```typescript
+// First element — Option<A>
+Sink.head<number>(); // Some(1) or None
+
+// Last element — Option<A>
+Sink.last<number>(); // Some(3) or None
+
+// Count all elements — number
+Sink.count; // 4
+
+// Sum numeric elements — number
+Sink.sum; // 10
+
+// First N elements — Chunk<A>
+Sink.take<number>(3); // Chunk(1, 2, 3)
+
+// Discard all — void (for side effects upstream)
+Sink.drain;
+
+// Measure execution time — Duration
+Sink.timed;
+```
+
+### Effectful Consumption
+
+```typescript
+// Run effect for each element
+Sink.forEach<number>(n => Console.log(`Got: ${n}`));
+```
+
+### Success / Failure
+
+```typescript
+// Immediately succeed without consuming
+Sink.succeed(0); // always returns 0
+
+// Immediately fail without consuming
+Sink.fail("oops"); // fails with "oops"
+```
+
+## Collecting
+
+```typescript
+// All elements into Chunk
+Sink.collectAll<number>();
+
+// First N elements into Chunk
+Sink.collectAllN<number>(3);
+
+// While predicate holds
+Sink.collectAllWhile<number>(n => n !== 0);
+
+// Into HashSet (unique elements)
+Sink.collectAllToSet<number>();
+
+// Into HashSet with max size
+Sink.collectAllToSetN<number>(3);
+
+// Into HashMap with key + merge functions
+Sink.collectAllToMap<number, number>(
+  n => n % 3, // key function
+  (a, b) => a + b // merge values with same key
+);
+
+// Into HashMap with max keys
+Sink.collectAllToMapN<number, number>(
+  3, // max keys
+  n => n, // key function
+  (a, b) => a + b // merge function
+);
+```
+
+## Folding
+
+```typescript
+// Standard left fold — processes entire stream
+Sink.foldLeft(0, (acc, n) => acc + n);
+
+// Fold with early termination
+Sink.fold(
+  0, // initial
+  sum => sum <= 10, // continue while true
+  (acc, n) => acc + n // fold operation
+);
+// Stops when sum > 10
+
+// Fold up to N elements
+Sink.foldUntil(0, 3, (acc, n) => acc + n);
+// Folds first 3 elements only
+
+// Fold by weight — resets when maxCost exceeded
+Sink.foldWeighted({
+  initial: Chunk.empty<number>(),
+  maxCost: 3,
+  cost: () => 1, // weight per element
+  body: (acc, el) => Chunk.append(acc, el),
+});
+```
+
+## Operations
+
+### Transforming Input
+
+`Sink.mapInput` adapts what a sink accepts. `Sink.map` transforms the output.
+
+```typescript
+// Convert string input to numbers for Sink.sum
+const stringSum = Sink.sum.pipe(Sink.mapInput((s: string) => Number.parseFloat(s)));
+// Stream.run(Stream.make("1", "2", "3"), stringSum) → 6
+```
+
+### Transforming Both Input and Output
+
+```typescript
+const sumAsString = Sink.dimap(Sink.sum, {
+  onInput: (s: string) => Number.parseFloat(s),
+  onDone: n => String(n),
+});
+// Stream.run(Stream.make("1", "2", "3"), sumAsString) → "6"
+```
+
+### Filtering Input
+
+```typescript
+// Only collect positive numbers in chunks of 3
+Sink.collectAllN<number>(3).pipe(Sink.filterInput(n => n > 0));
+```
+
+### Mapping Output
+
+```typescript
+// Transform the result
+Sink.count.pipe(Sink.map(n => `Total: ${n}`));
+
+// Replace the result with a constant
+Sink.forEach(Console.log).pipe(Sink.as(42));
+```
+
+## Concurrency
+
+### Zip — Combine Two Sinks
+
+Run two sinks concurrently and combine results into a tuple:
+
+```typescript
+const sink1 = Sink.forEach((s: string) => Console.log(`sink 1: ${s}`)).pipe(Sink.as(1));
+
+const sink2 = Sink.forEach((s: string) => Console.log(`sink 2: ${s}`)).pipe(Sink.as(2));
+
+const combined = Sink.zip(sink1, sink2, { concurrent: true });
+// Stream.run(stream, combined) → [1, 2]
+```
+
+### Race — First Completion Wins
+
+```typescript
+const winner = Sink.race(sink1, sink2);
+// Result from whichever sink finishes first
+```
+
+## Leftovers
+
+When a sink doesn't consume all elements, the rest are "leftovers."
+
+```typescript
+// Collect leftovers as a tuple: [result, Chunk<leftover>]
+const withLeftovers = Sink.take<number>(3).pipe(Sink.collectLeftover);
+// Stream.run(Stream.make(1,2,3,4,5), withLeftovers)
+// → [Chunk(1,2,3), Chunk(4,5)]
+
+// Discard leftovers
+const noLeftovers = Sink.take<number>(3).pipe(Sink.ignoreLeftover);
+```
+
+## Using Sinks with Stream.transduce
+
+`Stream.transduce` repeatedly applies a sink to a stream, producing a stream of sink results:
+
+```typescript
+const chunked = Stream.make(1, 2, 3, 4, 5, 6, 7).pipe(
+  Stream.transduce(Sink.collectAllN<number>(3))
+);
+// Produces: Chunk(1,2,3), Chunk(4,5,6), Chunk(7)
+
+// Batch with weighted elements
+const batched = stream.pipe(
+  Stream.transduce(
+    Sink.foldWeighted({
+      initial: Chunk.empty<number>(),
+      maxCost: 100,
+      cost: (_, el) => el,
+      body: (acc, el) => Chunk.append(acc, el),
+    })
+  )
+);
+```
+
+## Quick Reference Table
+
+| Sink                         | Result          | Consumes           |
+| ---------------------------- | --------------- | ------------------ |
+| `Sink.head()`                | `Option<A>`     | First element      |
+| `Sink.last()`                | `Option<A>`     | All elements       |
+| `Sink.count`                 | `number`        | All elements       |
+| `Sink.sum`                   | `number`        | All numeric        |
+| `Sink.take(n)`               | `Chunk<A>`      | First N            |
+| `Sink.drain`                 | `void`          | All (discards)     |
+| `Sink.timed`                 | `Duration`      | All (measures)     |
+| `Sink.forEach(f)`            | `void`          | All (side effects) |
+| `Sink.collectAll()`          | `Chunk<A>`      | All elements       |
+| `Sink.collectAllN(n)`        | `Chunk<A>`      | First N            |
+| `Sink.collectAllWhile(p)`    | `Chunk<A>`      | While predicate    |
+| `Sink.collectAllToSet()`     | `HashSet<A>`    | All (unique)       |
+| `Sink.collectAllToMap(k, m)` | `HashMap<K, A>` | All (grouped)      |
+| `Sink.foldLeft(s, f)`        | `S`             | All elements       |
+| `Sink.fold(s, cont, f)`      | `S`             | Until condition    |
+| `Sink.foldUntil(s, n, f)`    | `S`             | First N            |
+| `Sink.foldWeighted(opts)`    | `S`             | Until max cost     |
+
+## Import Convention
+
+```typescript
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import * as Chunk from "effect/Chunk";
+import * as Console from "effect/Console";
+```