@thomasfosterau/effect-parse 0.2.0 → 0.3.0

package/dist/ParserSchema.d.ts

@@ -1,6 +1,28 @@
+import * as Result from "effect/Result";
 import { Parser } from "./Parser.js";
 import * as Schema from "effect/Schema";
 //#region src/ParserSchema.d.ts
+/**
+ * The key of the annotation that says how a schema is written as text
+ * ({@link Annotation}), namespaced to this package so it cannot collide with
+ * another library's. {@link annotate} sets it.
+ *
+ * @since 0.3.0
+ * @category annotations
+ */
+export declare const annotationKey: "@thomasfosterau/effect-parse/ParserSchema";
+declare module "effect/Schema" {
+  namespace Annotations {
+    interface Annotations {
+      /**
+       * How the schema is written as text, read by `ParserSchema.toParser`
+       * and `ParserSchema.toPrinter`: a parser for the schema's type, or a
+       * `ParserSchema.Grammar`.
+       */
+      readonly [annotationKey]?: Annotation<any> | undefined;
+    }
+  }
+}
 /**
  * Options for {@link make}.
  *
@@ -28,5 +50,181 @@ export interface ParserSchema<A> extends Schema.decodeTo<Schema.declare<A>, Sche
  * @category constructors
  */
 export declare const make: <A, E>(parser: Parser<A, E, never, string>, options?: Options<A>) => ParserSchema<A>;
+/**
+ * How a schema is written as text, given in its annotation (see
+ * {@link annotate}) and read by {@link toParser} and {@link toPrinter}.
+ * Every field is optional; a schema without one is written as described on
+ * {@link toParser}.
+ *
+ * @since 0.3.0
+ * @category models
+ */
+export interface Grammar<A = unknown> {
+  /**
+   * Parses the schema's type outright, replacing what {@link toParser} would
+   * derive. Its output is still validated against the schema's type and
+   * checks, and its failures' causes become `SchemaError`s with their message.
+   * Give a {@link Grammar.print} with it, or the schema cannot be printed.
+   */
+  readonly parser?: Parser<A, unknown, never, string> | undefined;
+  /** Writes a value as the text {@link Grammar.parser} reads, replacing what {@link toPrinter} would derive. */
+  readonly print?: ((value: A) => string) | undefined;
+  /** Text written before the value. */
+  readonly prefix?: string | undefined;
+  /** Text written after the value. */
+  readonly suffix?: string | undefined;
+  /** Text written between the fields of a struct, the elements of a tuple or array, or the entries of a record. */
+  readonly separator?: string | undefined;
+  /**
+   * Text written between a key and its value. On a struct, it writes each
+   * field as `key`, separator, value, in any order; records always need one.
+   */
+  readonly keySeparator?: string | undefined;
+  /**
+   * Whether whitespace may surround the text this schema writes (its prefix,
+   * suffix and separators), and whitespace around unannotated strings is
+   * trimmed. Inherited by the schemas inside it. Printers write no
+   * whitespace.
+   */
+  readonly whitespace?: boolean | undefined;
+}
+/**
+ * The value of the annotation under {@link annotationKey}: a
+ * {@link Grammar}, or a parser for the schema's type (short for
+ * `{ parser }`, which cannot be printed).
+ *
+ * @since 0.3.0
+ * @category models
+ */
+export type Annotation<A = unknown> = Grammar<A> | Parser<A, unknown, never, string>;
+/**
+ * Annotates a schema with how it is written as text, for {@link toParser}
+ * and {@link toPrinter}. The same as
+ * `schema.annotate({ [ParserSchema.annotationKey]: annotation })`, except
+ * that the parser's output must have the schema's type.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { ParserSchema } from "@thomasfosterau/effect-parse"
+ *
+ * const Point = Schema.Struct({ x: Schema.Int, y: Schema.Int }).pipe(
+ *   ParserSchema.annotate({ prefix: "(", separator: ",", suffix: ")" })
+ * )
+ * ```
+ *
+ * @since 0.3.0
+ * @category annotations
+ */
+export declare const annotate: {
+  <A = never>(annotation: Annotation<A>): <S extends Schema.Top>(self: S & ([A] extends [S["Type"]] ? unknown : never)) => S["Rebuild"];
+  <S extends Schema.Top>(self: S, annotation: Annotation<S["Type"]>): S["Rebuild"];
+};
+/**
+ * Derives a parser from a schema. The parser reads the text the schema's
+ * annotations ({@link Grammar}) describe and returns a value of the schema's
+ * type, which the schema's checks and transformations have already
+ * validated; their failures become parse errors whose `cause` is the
+ * `SchemaError`.
+ *
+ * Without an annotation, a schema is parsed as follows:
+ *
+ * - `String`: one or more characters up to the next separator, key
+ *   separator, suffix or literal around it (to the end of the input at the
+ *   top level).
+ * - `Number`: a decimal number (`Ascii.float`), or a decimal integer when
+ *   the schema checks `isInt` (as `Schema.Int` does). `BigInt`: a decimal
+ *   integer. `Boolean`: `true` or `false`. `Null`: `null`. `Undefined` and
+ *   `Void`: nothing.
+ * - `Literal`, `Enum` and `TemplateLiteral`: their text.
+ * - `Struct` and `Tuple`: their fields or elements in order, between
+ *   separators; an optional one may be left out along with its separator.
+ *   `Array`: elements between separators.
+ * - `Record`, and `Struct` with a `keySeparator`: `key`, key separator,
+ *   value entries in any order, between separators.
+ * - `Union`: the first member that parses, in order (literals longest
+ *   first). `suspend`: recursion.
+ * - A transformation (a `Class`, `NumberFromString`, ...): its encoded side,
+ *   decoded by the schema. A grammar on it with a separator applies to the
+ *   encoded side.
+ *
+ * A parser that fails where the schema starts reports the schema's
+ * `identifier` annotation (or its `expected` annotation, unless that belongs
+ * to a check) as what it expected. Other declarations, `Unknown`, `Any`,
+ * symbols and `object` need a parser in their annotation; without one,
+ * `toParser` throws. Transformations must decode synchronously.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Parser, ParserSchema } from "@thomasfosterau/effect-parse"
+ *
+ * const Version = Schema.Struct({ major: Schema.Int, minor: Schema.Int }).pipe(
+ *   ParserSchema.annotate({ separator: "." })
+ * )
+ *
+ * Parser.parse(ParserSchema.toParser(Version), "1.2") // Result.succeed({ major: 1, minor: 2 })
+ * ```
+ *
+ * @since 0.3.0
+ * @category derivation
+ */
+export declare const toParser: <S extends Schema.ConstraintDecoder<unknown>>(schema: S) => Parser<S["Type"], Schema.SchemaError, never, string>;
+/**
+ * Derives a printer from a schema: it writes a value of the schema's type as
+ * the text {@link toParser} reads, following the same annotations, with no
+ * optional whitespace. Transformations encode the value first, and a
+ * {@link Grammar.print} replaces the derived printer.
+ *
+ * The printer fails with a `SchemaError` when the value is not of the
+ * schema's type, or cannot be written so that it reads back: a string that
+ * is empty or contains a character that would end it (a separator, a
+ * suffix), or a part annotated with a parser but no `print`. Where the
+ * grammar is ambiguous (an optional field followed by a field of the same
+ * type), the text can still read back as a different value;
+ * {@link fromSchema} checks that it doesn't.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { ParserSchema } from "@thomasfosterau/effect-parse"
+ *
+ * const Version = Schema.Struct({ major: Schema.Int, minor: Schema.Int }).pipe(
+ *   ParserSchema.annotate({ separator: "." })
+ * )
+ *
+ * ParserSchema.toPrinter(Version)({ major: 1, minor: 2 }) // Result.succeed("1.2")
+ * ```
+ *
+ * @since 0.3.0
+ * @category derivation
+ */
+export declare const toPrinter: <S extends Schema.ConstraintCodec<unknown, unknown, unknown, never>>(schema: S) => ((value: S["Type"]) => Result.Result<string, Schema.SchemaError>);
+/**
+ * Creates a schema that decodes a string with the parser {@link toParser}
+ * derives from `schema`, into `schema`'s type, and encodes with the printer
+ * {@link toPrinter} derives, or with `encode` when given. A derived printer's
+ * text is parsed back, and encoding fails unless it gives a value equivalent
+ * to the one encoded, so decoding what was encoded always gives it back.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { ParserSchema } from "@thomasfosterau/effect-parse"
+ *
+ * const Pair = ParserSchema.fromSchema(
+ *   Schema.Tuple([Schema.String, Schema.Number]).pipe(ParserSchema.annotate({ separator: "=" }))
+ * )
+ *
+ * Schema.decodeUnknownSync(Pair)("width=10") // ["width", 10]
+ * Schema.encodeSync(Pair)(["height", 2]) // "height=2"
+ * ```
+ *
+ * @since 0.3.0
+ * @category constructors
+ */
+export declare const fromSchema: <S extends Schema.ConstraintCodec<unknown, unknown, never, never> & Schema.Top>(schema: S, options?: {
+  readonly encode?: ((value: S["Type"]) => string) | undefined;
+}) => Schema.decodeTo<Schema.toType<S>, Schema.String>;
 //#endregion
 //# sourceMappingURL=ParserSchema.d.ts.map

package/dist/ParserSchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParserSchema.d.ts","names":[],"sources":["../src/ParserSchema.ts"],"mappings":";;;;;;;;;iBAyCiB,QAAQ;;WAEd,WAAW,OAAO;;WAElB;;;;;;;;iBASM,aAAa,WAAW,OAAO,SAAS,OAAO,QAAQ,IAAI,OAAO;;;;;;;;qBAStE,OAAQ,GAAG,GAAG,QAAQ,OAAO,GAAG,mBAAmB,UAAU,QAAQ,OAAK,aAAa"}
+{"version":3,"file":"ParserSchema.d.ts","names":[],"sources":["../src/ParserSchema.ts"],"mappings":";;;;;;;;;;;;qBA4Da;;YAGD;cACE;;;;;;gBAME,iBAAiB;;;;;;;;;;iBAWhB,QAAQ;;WAEd,WAAW,OAAO;;WAElB;;;;;;;;iBASM,aAAa,WAAW,OAAO,SAAS,OAAO,QAAQ,IAAI,OAAO;;;;;;;;qBA0CtE,OAAQ,GAAG,GAAG,QAAQ,OAAO,GAAG,mBAAmB,UAAU,QAAQ,OAAK,aAAa;;;;;;;;;;iBAuBnF,QAAQ;;;;;;;WAOd,SAAS,OAAO;;WAEhB,UAAU,OAAO;;WAEjB;;WAEA;;WAEA;;;;;WAKA;;;;;;;WAOA;;;;;;;;;;YAWC,WAAW,eAAe,QAAQ,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;qBAqB7C;GAEV,WACC,YAAY,WAAW,MACrB,UAAU,OAAO,KAAK,MAAM,MAAM,YAAY,kCAAkC;GACnF,UAAU,OAAO,KAAK,MAAM,GAAG,YAAY,WAAW,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAsDzD,WAAY,UAAU,OAAO,4BACxC,QAAQ,MACP,OAAO,WAAW,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmCf,YAAa,UAAU,OAAO,mDACzC,QAAQ,QACL,OAAO,cAAc,OAAO,eAAe,OAAO;;;;;;;;;;;;;;;;;;;;;;;;qBAmC1C,aAAc,UAAU,OAAO,kDAAkD,OAAO,KACnG,QAAQ,GACR;WAAqB,WAAW,OAAO;MACtC,OAAO,SAAS,OAAO,OAAO,IAAI,OAAO"}