is-kit 1.11.2 → 1.11.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -170,9 +170,24 @@ const isSlug = (value: unknown): value is string =>
170
170
  isString(value) && /^[a-z0-9-]+$/.test(value);
171
171
  ```
172
172
 
173
- For AI agents or repository-wide conventions, copy
174
- [docs/agent-rules.md](./docs/agent-rules.md) into the consumer repository's
175
- agent instructions.
173
+ ### AI agent setup
174
+
175
+ Add the recommended `is-kit` selection and usage rules to a repository's AI
176
+ agent instructions:
177
+
178
+ ```bash
179
+ npx is-kit init-agent
180
+ ```
181
+
182
+ The command updates an `is-kit`-managed section in `AGENTS.md` without
183
+ overwriting other instructions. If a repository uses `CLAUDE.md`, target it
184
+ explicitly:
185
+
186
+ ```bash
187
+ npx is-kit init-agent --target claude
188
+ ```
189
+
190
+ See [docs/agent-rules.md](./docs/agent-rules.md) for the installed rules.
176
191
 
177
192
  ## ⌚ A 30-second Mental Model
178
193
 
package/bin/is-kit.mjs ADDED
@@ -0,0 +1,103 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { access, readFile, writeFile } from 'node:fs/promises';
4
+ import { dirname, resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ const START_MARKER = '<!-- is-kit-agent-rules:start -->';
8
+ const END_MARKER = '<!-- is-kit-agent-rules:end -->';
9
+ const TARGET_FILES = {
10
+ agents: 'AGENTS.md',
11
+ claude: 'CLAUDE.md'
12
+ };
13
+
14
+ const usage = `Usage: is-kit init-agent [--target agents|claude]
15
+
16
+ Adds or updates the is-kit rules in AGENTS.md (default) or CLAUDE.md.`;
17
+
18
+ const isHelpRequested = (args) =>
19
+ args.includes('--help') || args.includes('-h');
20
+
21
+ const fileExists = async (path) => {
22
+ try {
23
+ await access(path);
24
+ return true;
25
+ } catch {
26
+ return false;
27
+ }
28
+ };
29
+
30
+ const parseTarget = (args) => {
31
+ const targetIndex = args.indexOf('--target');
32
+
33
+ if (targetIndex === -1) {
34
+ return 'agents';
35
+ }
36
+
37
+ const target = args[targetIndex + 1];
38
+ if (!Object.hasOwn(TARGET_FILES, target)) {
39
+ throw new Error(`Unknown target: ${target ?? '(missing)'}`);
40
+ }
41
+
42
+ return target;
43
+ };
44
+
45
+ const updateManagedSection = (existingContent, rules) => {
46
+ const section = `${START_MARKER}\n${rules.trim()}\n${END_MARKER}`;
47
+ const startIndex = existingContent.indexOf(START_MARKER);
48
+ const endIndex = existingContent.indexOf(END_MARKER);
49
+
50
+ if (startIndex === -1 && endIndex === -1) {
51
+ const separator = existingContent.trim().length === 0 ? '' : '\n\n';
52
+ return `${existingContent.trimEnd()}${separator}${section}\n`;
53
+ }
54
+
55
+ if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
56
+ throw new Error('The existing is-kit managed section is malformed.');
57
+ }
58
+
59
+ const afterSection = endIndex + END_MARKER.length;
60
+ return `${existingContent.slice(0, startIndex)}${section}${existingContent.slice(afterSection)}`;
61
+ };
62
+
63
+ const initAgent = async (args) => {
64
+ const target = parseTarget(args);
65
+ const targetPath = resolve(process.cwd(), TARGET_FILES[target]);
66
+ const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
67
+ const rulesPath = resolve(packageRoot, 'docs/agent-rules.md');
68
+ const rules = await readFile(rulesPath, 'utf8');
69
+ const existingContent = (await fileExists(targetPath))
70
+ ? await readFile(targetPath, 'utf8')
71
+ : '';
72
+
73
+ await writeFile(
74
+ targetPath,
75
+ updateManagedSection(existingContent, rules),
76
+ 'utf8'
77
+ );
78
+ process.stdout.write(
79
+ `Updated ${TARGET_FILES[target]} with is-kit agent rules.\n`
80
+ );
81
+ };
82
+
83
+ const main = async () => {
84
+ const [command, ...args] = process.argv.slice(2);
85
+
86
+ if (command === 'init-agent') {
87
+ if (isHelpRequested(args)) {
88
+ process.stdout.write(`${usage}\n`);
89
+ return;
90
+ }
91
+
92
+ await initAgent(args);
93
+ return;
94
+ }
95
+
96
+ process.stdout.write(`${usage}\n`);
97
+ process.exitCode = command === undefined || command === '--help' ? 0 : 1;
98
+ };
99
+
100
+ main().catch((error) => {
101
+ process.stderr.write(`is-kit: ${error.message}\n`);
102
+ process.exitCode = 1;
103
+ });
package/dist/index.d.mts CHANGED
@@ -39,6 +39,13 @@ type SchemaField = Predicate<unknown> | OptionalSchemaField<Predicate<unknown>>;
39
39
  * Object schema consumed by `struct`.
40
40
  */
41
41
  type Schema = Readonly<Record<string, SchemaField>>;
42
+ /**
43
+ * Configures object-key validation for `struct` and `typedStruct`.
44
+ */
45
+ type StructOptions = Readonly<{
46
+ /** Rejects extra own enumerable string-key properties when enabled. */
47
+ exact?: boolean;
48
+ }>;
42
49
  /**
43
50
  * Object schema shape preserving concrete keys.
44
51
  */
@@ -686,20 +693,19 @@ declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSc
686
693
  * properties not in `schema`.
687
694
  * @returns Predicate that narrows to the inferred struct type.
688
695
  */
689
- declare function struct<const S extends SchemaShape<S>>(schema: S, options?: {
690
- exact?: boolean;
691
- }): Predicate<InferSchema<S>>;
696
+ declare function struct<const S extends SchemaShape<S>>(schema: S, options?: StructOptions): Predicate<InferSchema<S>>;
692
697
 
693
698
  /**
694
699
  * Creates a `struct` builder checked against an existing object type.
695
700
  * Optional target keys must also be declared with `optionalKey` so type drift
696
701
  * stays visible when the target type changes.
697
702
  *
703
+ * Target-compatible field guards may narrow further than the target field type;
704
+ * the returned predicate preserves those narrower inferred types.
705
+ *
698
706
  * @returns Builder that rejects missing, extra, or incompatible struct fields.
699
707
  */
700
- declare function typedStruct<T extends object>(): <const S extends TypedStructShape<T>>(fields: TypedStructFields<T, S>, options?: {
701
- exact?: boolean;
702
- }) => Predicate<InferSchema<TypedStructFields<T, S>>>;
708
+ declare function typedStruct<T extends object>(): <const S extends TypedStructShape<T>>(fields: TypedStructFields<T, S>, options?: StructOptions) => Predicate<InferSchema<TypedStructFields<T, S>>>;
703
709
 
704
710
  /**
705
711
  * Validates a fixed-length tuple by applying element-wise guards.
@@ -763,4 +769,4 @@ declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPred
763
769
  */
764
770
  declare const toBooleanPredicates: <A>(predicates: readonly ((value: A) => boolean)[]) => ReadonlyArray<(value: A) => boolean>;
765
771
 
766
- export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type NoExtraKeys, type OptionalObjectKeys, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type RequiredObjectKeys, type Schema, type SchemaField, type TypedStructFields, type TypedStructShape, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
772
+ export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type NoExtraKeys, type OptionalObjectKeys, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type RequiredObjectKeys, type Schema, type SchemaField, type StructOptions, type TypedStructFields, type TypedStructShape, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
package/dist/index.d.ts CHANGED
@@ -39,6 +39,13 @@ type SchemaField = Predicate<unknown> | OptionalSchemaField<Predicate<unknown>>;
39
39
  * Object schema consumed by `struct`.
40
40
  */
41
41
  type Schema = Readonly<Record<string, SchemaField>>;
42
+ /**
43
+ * Configures object-key validation for `struct` and `typedStruct`.
44
+ */
45
+ type StructOptions = Readonly<{
46
+ /** Rejects extra own enumerable string-key properties when enabled. */
47
+ exact?: boolean;
48
+ }>;
42
49
  /**
43
50
  * Object schema shape preserving concrete keys.
44
51
  */
@@ -686,20 +693,19 @@ declare function optionalKey<G extends Predicate<unknown>>(guard: G): OptionalSc
686
693
  * properties not in `schema`.
687
694
  * @returns Predicate that narrows to the inferred struct type.
688
695
  */
689
- declare function struct<const S extends SchemaShape<S>>(schema: S, options?: {
690
- exact?: boolean;
691
- }): Predicate<InferSchema<S>>;
696
+ declare function struct<const S extends SchemaShape<S>>(schema: S, options?: StructOptions): Predicate<InferSchema<S>>;
692
697
 
693
698
  /**
694
699
  * Creates a `struct` builder checked against an existing object type.
695
700
  * Optional target keys must also be declared with `optionalKey` so type drift
696
701
  * stays visible when the target type changes.
697
702
  *
703
+ * Target-compatible field guards may narrow further than the target field type;
704
+ * the returned predicate preserves those narrower inferred types.
705
+ *
698
706
  * @returns Builder that rejects missing, extra, or incompatible struct fields.
699
707
  */
700
- declare function typedStruct<T extends object>(): <const S extends TypedStructShape<T>>(fields: TypedStructFields<T, S>, options?: {
701
- exact?: boolean;
702
- }) => Predicate<InferSchema<TypedStructFields<T, S>>>;
708
+ declare function typedStruct<T extends object>(): <const S extends TypedStructShape<T>>(fields: TypedStructFields<T, S>, options?: StructOptions) => Predicate<InferSchema<TypedStructFields<T, S>>>;
703
709
 
704
710
  /**
705
711
  * Validates a fixed-length tuple by applying element-wise guards.
@@ -763,4 +769,4 @@ declare const everyOwnEnumerableEntry: (values: Record<string, unknown>, keyPred
763
769
  */
764
770
  declare const toBooleanPredicates: <A>(predicates: readonly ((value: A) => boolean)[]) => ReadonlyArray<(value: A) => boolean>;
765
771
 
766
- export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type NoExtraKeys, type OptionalObjectKeys, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type RequiredObjectKeys, type Schema, type SchemaField, type TypedStructFields, type TypedStructShape, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
772
+ export { type ChainResult, type Guard, type GuardedOf, type GuardedWithin, type InferSchema, type NoExtraKeys, type OptionalObjectKeys, type OptionalSchemaField, type OutOfGuards, type ParseResult, type Predicate, type Primitive, type Refine, type RefineChain, type Refinement, type RequiredObjectKeys, type Schema, type SchemaField, type StructOptions, type TypedStructFields, type TypedStructShape, and, andAll, arrayOf, assert, define, equals, equalsBy, equalsKey, everyArrayValue, everyMapEntry, everyOwnEnumerableEntry, everySetValue, everyTupleValue, guardIn, hasKey, hasKeys, isArray, isArrayBuffer, isAsyncIterable, isBigInt, isBlob, isBoolean, isDataView, isDate, isError, isFile, isFiniteNumber, isFunction, isInfiniteNumber, isInstanceOf, isInteger, isIterable, isMap, isNaN, isNegative, isNil, isNull, isNumber, isNumberPrimitive, isObject, isPlainObject, isPositive, isPrimitive, isPromiseLike, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isURL, isUndefined, isWeakMap, isWeakSet, isZero, lazy, mapOf, narrowKeyTo, nonEmptyArrayOf, nonNull, not, nullable, nullish, oneOf, oneOfValues, optional, optionalKey, or, predicateToRefine, recordOf, required, safeJsonParse, safeParse, safeParseWith, setOf, struct, toBooleanPredicates, tupleOf, typedStruct };
package/dist/index.js CHANGED
@@ -473,7 +473,9 @@ var isOptionalSchemaField = define(
473
473
  var hasRequiredKeys = (obj, entries) => (
474
474
  // WHY: Required fields must be own properties; inherited values should not
475
475
  // satisfy a schema because `struct` models object payload shape, not prototype chains.
476
- entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]))
476
+ entries.every(
477
+ ([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key])
478
+ )
477
479
  );
478
480
  var hasValidOptionalKeys = (obj, entries) => (
479
481
  // WHY: Optional keys are validated only when present. Missing keys stay valid
package/dist/index.mjs CHANGED
@@ -369,7 +369,9 @@ var isOptionalSchemaField = define(
369
369
  var hasRequiredKeys = (obj, entries) => (
370
370
  // WHY: Required fields must be own properties; inherited values should not
371
371
  // satisfy a schema because `struct` models object payload shape, not prototype chains.
372
- entries.every(([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key]))
372
+ entries.every(
373
+ ([key, guard]) => hasOwnPropertyKey(obj, key) && guard(obj[key])
374
+ )
373
375
  );
374
376
  var hasValidOptionalKeys = (obj, entries) => (
375
377
  // WHY: Optional keys are validated only when present. Missing keys stay valid
@@ -1,8 +1,11 @@
1
1
  # is-kit Agent Rules
2
2
 
3
- Copy this into a consumer repository's `AGENTS.md`, `CLAUDE.md`, or
4
- `.agents/rules/is-kit.md` when AI agents generate or review code that uses
5
- `is-kit`.
3
+ Use these rules when generating or reviewing code that uses `is-kit`.
4
+
5
+ Choose `is-kit` when the task needs reusable TypeScript type guards, natural
6
+ control-flow narrowing, and lightweight runtime checks. Prefer a schema
7
+ validator such as Zod when the task requires structured validation errors,
8
+ data transformations, or a schema-first workflow.
6
9
 
7
10
  ## Usage Rules
8
11
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "is-kit",
3
- "version": "1.11.2",
4
- "description": "Make 'isXXX' easier. Let's make your code type safe and more readable!",
3
+ "version": "1.11.4",
4
+ "description": "Zero-dependency TypeScript runtime validation toolkit for composable type guards and natural type narrowing.",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
7
7
  "types": "./dist/index.d.ts",
@@ -12,15 +12,24 @@
12
12
  "require": "./dist/index.js"
13
13
  }
14
14
  },
15
+ "bin": {
16
+ "is-kit": "./bin/is-kit.mjs"
17
+ },
15
18
  "keywords": [
16
- "is",
17
- "isXXX",
18
- "isKit",
19
- "type guards",
20
- "type safe",
21
- "type checking"
19
+ "typescript",
20
+ "type-guard",
21
+ "type-guards",
22
+ "runtime-validation",
23
+ "validation",
24
+ "validator",
25
+ "type-safety",
26
+ "type-narrowing",
27
+ "unknown",
28
+ "schema",
29
+ "zero-dependency"
22
30
  ],
23
31
  "files": [
32
+ "bin",
24
33
  "dist",
25
34
  "docs/agent-rules.md",
26
35
  "README.md",
@@ -34,7 +43,7 @@
34
43
  "bugs": {
35
44
  "url": "https://github.com/nyaomaru/is-kit/issues"
36
45
  },
37
- "homepage": "https://github.com/nyaomaru/is-kit#readme",
46
+ "homepage": "https://is-kit-docs.vercel.app/",
38
47
  "author": "nyaomaru",
39
48
  "license": "MIT",
40
49
  "devDependencies": {