Make the json family readonly

Author: nvie

src/core/Decoder.ts

@@ -115,7 +115,7 @@ export interface Decoder<T> {
    * > be covered more elegantly by `.transform()`, `.refine()`, or `.pipe()`
    * > instead._
    */
-  then<V>(next: Next<V, T>, forceFlags?: number): Decoder<V>;  // XXX This should not be public API
+  then<V>(next: Next<V, T>, forceFlags?: number): Decoder<V>; // XXX This should not be public API
 
   /**
    * Send the output of this decoder as input to another decoder.
@@ -362,7 +362,7 @@ export function define<T>(fn: AcceptanceFn<T>, flags = NONE): Decoder<T> {
         // message instead
         return err(annotate(result.error, message));
       }
-    });
+    }, flags);
   }
 
   return brand({
@@ -412,13 +412,13 @@ export function defineReadonly<T>(
 /**
  * Ensures that the given decoder is read-only.
  */
-export function readonly<T>(decoder: ReadonlyDecoder<T>): ReadonlyDecoder<T> {
+export function readonly<T>(decoder: Decoder<T>): ReadonlyDecoder<T> {
   if (!decoder.isReadonly) {
     const err = new Error('The provided decoder must be read-only');
     Error.captureStackTrace(err, readonly);
     throw err;
   }
-  return decoder;
+  return decoder as ReadonlyDecoder<T>;
 }
 
 /** @internal */

src/index.ts

@@ -8,6 +8,7 @@ export { date, datelike, iso8601 } from './dates';
 export type { JSONArray, JSONObject, JSONValue } from './json';
 export { json, jsonArray, jsonObject } from './json';
 export type { SizeOptions } from './lib/size-options';
+export type { LazyOptions } from './misc';
 export { instanceOf, lazy, prep } from './misc';
 export { anyNumber, integer, number, positiveInteger, positiveNumber } from './numbers';
 export { bigint } from './numbers';

src/json.ts

@@ -1,13 +1,13 @@
-import type { Decoder } from '~/core';
+import type { ReadonlyDecoder } from '~/core';
 
 import { array } from './arrays';
-import { null_ } from './basics';
 import { boolean } from './booleans';
-import { record } from './collections';
-import { lazy } from './misc';
+import { either } from './unions';
+import { null_ } from './basics';
 import { number } from './numbers';
+import { lazy } from './misc';
+import { record } from './collections';
 import { string } from './strings';
-import { either } from './unions';
 
 export type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
 export type JSONObject = { [key: string]: JSONValue | undefined };
@@ -16,12 +16,16 @@ export type JSONArray = JSONValue[];
 /**
  * Accepts objects that contain only valid JSON values.
  */
-export const jsonObject: Decoder<JSONObject> = lazy(() => record(json));
+export const jsonObject: ReadonlyDecoder<JSONObject> = lazy(() => record(json), {
+  readonly: true,
+});
 
 /**
  * Accepts arrays that contain only valid JSON values.
  */
-export const jsonArray: Decoder<JSONArray> = lazy(() => array(json));
+export const jsonArray: ReadonlyDecoder<JSONArray> = lazy(() => array(json), {
+  readonly: true,
+});
 
 /**
  * Accepts any value that's a valid JSON value.
@@ -39,7 +43,7 @@ export const jsonArray: Decoder<JSONArray> = lazy(() => array(json));
  *     | JSONValue[]
  * ```
  */
-export const json: Decoder<JSONValue> = either(
+export const json: ReadonlyDecoder<JSONValue> = either(
   null_,
   string,
   number,

src/misc.ts

@@ -1,5 +1,5 @@
 import type { Decoder, ReadonlyDecoder } from '~/core';
-import { annotate, define, defineReadonly } from '~/core';
+import { annotate, define, defineReadonly, NONE, READONLY, readonly } from '~/core';
 
 // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
 export interface Klass<T> extends Function {
@@ -20,12 +20,30 @@ export function instanceOf<K extends Klass<any>>(klass: K): ReadonlyDecoder<Inst
   );
 }
 
+export type LazyOptions = {
+  /** Ensure that the provided factory function may only return readonly decoders. */
+  readonly: boolean;
+};
+
 /**
  * Lazily evaluate the given decoder. This is useful to build self-referential
  * types for recursive data structures.
  */
-export function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T> {
-  return define((blob) => decoderFn().decode(blob));
+export function lazy<T>(
+  decoderFn: () => ReadonlyDecoder<T>,
+  options: { readonly: true },
+): ReadonlyDecoder<T>;
+export function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T>;
+export function lazy<T>(decoderFn: () => Decoder<T>, options?: LazyOptions): Decoder<T> {
+  return define(
+    (blob) => {
+      let decoder = options?.readonly
+        ? readonly(decoderFn() as ReadonlyDecoder<T>)
+        : decoderFn();
+      return decoder.decode(blob);
+    },
+    options?.readonly ? READONLY : NONE,
+  );
 }
 
 /**

src/unions.ts

@@ -54,14 +54,20 @@ function nest(errText: string): string {
  * first one that accepts the input "wins". If all decoders reject the input,
  * the input gets rejected.
  */
-export function either<TDecoders extends readonly Decoder<unknown>[]>(
-  ...decoders: TDecoders
-): Decoder<DecoderType<TDecoders[number]>> {
+export function either<RDs extends readonly ReadonlyDecoder<unknown>[]>(
+  ...decoders: RDs
+): ReadonlyDecoder<DecoderType<RDs[number]>>;
+export function either<Ds extends readonly Decoder<unknown>[]>(
+  ...decoders: Ds
+): Decoder<DecoderType<Ds[number]>>;
+export function either<Ds extends readonly Decoder<unknown>[]>(
+  ...decoders: Ds
+): Decoder<DecoderType<Ds[number]>> {
   if (decoders.length === 0) {
     throw new Error('Pass at least one decoder to either()');
   }
 
-  type T = DecoderType<TDecoders[number]>;
+  type T = DecoderType<Ds[number]>;
   return define<T>(
     (blob, _, err) => {
       // Collect errors here along the way

test/json.test.ts

@@ -56,8 +56,7 @@ describe('decoder', () => {
     expect(() => decoder.verify({ a: new Date() })).toThrow();
   });
 
-  // XXX Implement
-  test.fails('readonliness', () => {
+  test('readonliness', () => {
     expect(decoder.isReadonly).toBe(true);
   });
 });
@@ -96,8 +95,7 @@ describe('jsonObject', () => {
     expect(() => decoder.verify({ a: new Date() })).toThrow();
   });
 
-  // XXX Implement
-  test.fails('readonliness', () => {
+  test('readonliness', () => {
     expect(decoder.isReadonly).toBe(true);
   });
 });
@@ -134,8 +132,7 @@ describe('jsonArray', () => {
     expect(() => decoder.verify({ a: new Date() })).toThrow();
   });
 
-  // XXX Implement
-  test.fails('readonliness', () => {
+  test('readonliness', () => {
     expect(decoder.isReadonly).toBe(true);
   });
 });