feat: Adds rules for text, mediumText, and tinyText (#1520)

readme.md

@@ -68,6 +68,9 @@ To save you some time, Rulr comes with the following rules.
 Since it's quite common to want to restrict the size of strings, Rulr comes with some convenient rules for doing just that.
 
 - [nonEmptyString](./src/sizedStrings/nonEmptyString/readme.md)
+- [tinyText](./src/sizedStrings/tinyText/readme.md) (0 - 255 characters)
+- [text](./src/sizedStrings/text/readme.md) (0 - 65,535 characters)
+- [mediumText](./src/sizedStrings/mediumText/readme.md) (0 - 16,777,215 characters)
 
 ### Constraining Strings
 

src/rulr.ts

@@ -113,8 +113,26 @@ export {
 	nonEmptyString,
 	isNonEmptyString,
 	NonEmptyString,
-	InvalidNonEmptyStringError
+	InvalidNonEmptyStringError,
 } from './sizedStrings/nonEmptyString/nonEmptyString'
+export {
+	mediumText,
+	isMediumText,
+	MediumText,
+	InvalidMediumTextError,
+} from './sizedStrings/mediumText/mediumText'
+export {
+	text,
+	isText,
+	Text,
+	InvalidTextError,
+} from './sizedStrings/text/text'
+export {
+	tinyText,
+	isTinyText,
+	TinyText,
+	InvalidTinyTextError,
+} from './sizedStrings/tinyText/tinyText'
 export { any } from './valueRules/any/any'
 export { bigint, isBigInt, InvalidBigIntError } from './valueRules/bigint/bigint'
 export { boolean, isBoolean, InvalidBooleanError } from './valueRules/boolean/boolean'

src/sizedStrings/mediumText/mediumText.test.ts

@@ -0,0 +1,24 @@
+import * as assert from 'assert'
+import { InvalidMediumTextError, MediumText, mediumText } from '../../rulr'
+
+test('mediumText should not allow invalid string input', () => {
+	const input = 0
+	assert.throws(() => mediumText(input), InvalidMediumTextError)
+})
+
+test('mediumText should allow valid text with 0 characters', () => {
+	const input = ''
+	const output: MediumText = mediumText(input)
+	assert.strictEqual(output, input)
+})
+
+test('mediumText should allow valid text with 16,777,215 characters', () => {
+	const input = Array(16777215).fill('a').join('')
+	const output: MediumText = mediumText(input)
+	assert.strictEqual(output, input)
+})
+
+test('mediumText should not allow invalid text with more than 16,777,215 characters', () => {
+	const input = Array(16777216).fill('a').join('')
+	assert.throws(() => mediumText(input), InvalidMediumTextError)
+})

src/sizedStrings/mediumText/mediumText.ts

@@ -0,0 +1,24 @@
+import { BaseError } from 'make-error'
+import { isString } from '../../valueRules/string/string'
+import { Constrained } from '../../core'
+
+export class InvalidMediumTextError extends BaseError {
+	constructor() {
+		super('expected no more than 255 characters')
+	}
+}
+
+export const mediumTextSymbol = Symbol()
+
+export type MediumText = Constrained<typeof mediumTextSymbol, string>
+
+export function isMediumText(input: unknown): input is MediumText {
+	return isString(input) && input.length <= 16777215
+}
+
+export function mediumText(input: unknown) {
+	if (isMediumText(input)) {
+		return input
+	}
+	throw new InvalidMediumTextError()
+}

src/sizedStrings/mediumText/readme.md

@@ -0,0 +1,40 @@
+# mediumText
+
+[Back to root readme.md](../../../readme.md)
+
+This function uses the `rulr.mediumText` guard to check the input is a valid medium text string ([max 16,777,215 characters](https://www.w3schools.com/sql/sql_datatypes.asp)) as shown in the example below. It should only throw `rulr.InvalidMediumTextError`.
+
+```ts
+import * as rulr from 'rulr'
+
+const constrainToExample = rulr.object({
+	required: {
+		example: rulr.mediumText,
+	},
+})
+
+type Example = rulr.Static<typeof constrainToExample>
+// {
+//   example: rulr.MediumText
+// }
+
+// Valid
+const example1: Example = constrainToExample({
+	example: '',
+})
+
+// Valid
+const example1: Example = constrainToExample({
+	example: Array(16777215).fill('a').join(''),
+})
+
+// Invalid: Too many characters
+const example2: Example = constrainToExample({
+	example: Array(16777216).fill('a').join(''),
+})
+
+// Invalid: Not a string
+const example3: Example = constrainToExample({
+	example: 1,
+})
+```

src/sizedStrings/text/readme.md

@@ -0,0 +1,40 @@
+# text
+
+[Back to root readme.md](../../../readme.md)
+
+This function uses the `rulr.text` guard to check the input is a valid text string ([max 65,535 characters](https://www.w3schools.com/sql/sql_datatypes.asp)) as shown in the example below. It should only throw `rulr.InvalidTextError`.
+
+```ts
+import * as rulr from 'rulr'
+
+const constrainToExample = rulr.object({
+	required: {
+		example: rulr.text,
+	},
+})
+
+type Example = rulr.Static<typeof constrainToExample>
+// {
+//   example: rulr.Text
+// }
+
+// Valid
+const example1: Example = constrainToExample({
+	example: '',
+})
+
+// Valid
+const example1: Example = constrainToExample({
+	example: Array(65535).fill('a').join(''),
+})
+
+// Invalid: Too many characters
+const example2: Example = constrainToExample({
+	example: Array(65536).fill('a').join(''),
+})
+
+// Invalid: Not a string
+const example3: Example = constrainToExample({
+	example: 1,
+})
+```

src/sizedStrings/text/text.test.ts

@@ -0,0 +1,24 @@
+import * as assert from 'assert'
+import { InvalidTextError, Text, text } from '../../rulr'
+
+test('text should not allow invalid string input', () => {
+	const input = 0
+	assert.throws(() => text(input), InvalidTextError)
+})
+
+test('text should allow valid text with 0 characters', () => {
+	const input = ''
+	const output: Text = text(input)
+	assert.strictEqual(output, input)
+})
+
+test('text should allow valid text with 65,535 characters', () => {
+	const input = Array(65535).fill('a').join('')
+	const output: Text = text(input)
+	assert.strictEqual(output, input)
+})
+
+test('text should not allow invalid text with more than 65,535 characters', () => {
+	const input = Array(65536).fill('a').join('')
+	assert.throws(() => text(input), InvalidTextError)
+})

src/sizedStrings/text/text.ts

@@ -0,0 +1,24 @@
+import { BaseError } from 'make-error'
+import { isString } from '../../valueRules/string/string'
+import { Constrained } from '../../core'
+
+export class InvalidTextError extends BaseError {
+	constructor() {
+		super('expected no more than 255 characters')
+	}
+}
+
+export const textSymbol = Symbol()
+
+export type Text = Constrained<typeof textSymbol, string>
+
+export function isText(input: unknown): input is Text {
+	return isString(input) && input.length <= 65535
+}
+
+export function text(input: unknown) {
+	if (isText(input)) {
+		return input
+	}
+	throw new InvalidTextError()
+}

src/sizedStrings/tinyText/readme.md

@@ -0,0 +1,40 @@
+# tinyText
+
+[Back to root readme.md](../../../readme.md)
+
+This function uses the `rulr.tinyText` guard to check the input is a valid tiny text string ([max 255 characters](https://www.w3schools.com/sql/sql_datatypes.asp)) as shown in the example below. It should only throw `rulr.InvalidTinyTextError`.
+
+```ts
+import * as rulr from 'rulr'
+
+const constrainToExample = rulr.object({
+	required: {
+		example: rulr.tinyText,
+	},
+})
+
+type Example = rulr.Static<typeof constrainToExample>
+// {
+//   example: rulr.TinyText
+// }
+
+// Valid
+const example1: Example = constrainToExample({
+	example: '',
+})
+
+// Valid
+const example1: Example = constrainToExample({
+	example: Array(255).fill('a').join(''),
+})
+
+// Invalid: Too many characters
+const example2: Example = constrainToExample({
+	example: Array(256).fill('a').join(''),
+})
+
+// Invalid: Not a string
+const example3: Example = constrainToExample({
+	example: 1,
+})
+```

src/sizedStrings/tinyText/tinyText.test.ts

@@ -0,0 +1,24 @@
+import * as assert from 'assert'
+import { InvalidTinyTextError, TinyText, tinyText } from '../../rulr'
+
+test('tinyText should not allow invalid string input', () => {
+	const input = 0
+	assert.throws(() => tinyText(input), InvalidTinyTextError)
+})
+
+test('tinyText should allow valid text with 0 characters', () => {
+	const input = ''
+	const output: TinyText = tinyText(input)
+	assert.strictEqual(output, input)
+})
+
+test('tinyText should allow valid text with 255 characters', () => {
+	const input = Array(255).fill('a').join('')
+	const output: TinyText = tinyText(input)
+	assert.strictEqual(output, input)
+})
+
+test('tinyText should not allow invalid text with more than 255 characters', () => {
+	const input = Array(256).fill('a').join('')
+	assert.throws(() => tinyText(input), InvalidTinyTextError)
+})

src/sizedStrings/tinyText/tinyText.ts

@@ -0,0 +1,24 @@
+import { BaseError } from 'make-error'
+import { isString } from '../../valueRules/string/string'
+import { Constrained } from '../../core'
+
+export class InvalidTinyTextError extends BaseError {
+	constructor() {
+		super('expected no more than 255 characters')
+	}
+}
+
+export const tinyTextSymbol = Symbol()
+
+export type TinyText = Constrained<typeof tinyTextSymbol, string>
+
+export function isTinyText(input: unknown): input is TinyText {
+	return isString(input) && input.length <= 255
+}
+
+export function tinyText(input: unknown) {
+	if (isTinyText(input)) {
+		return input
+	}
+	throw new InvalidTinyTextError()
+}