@atscript/typescript 0.1.21 → 0.1.23

package/dist/utils.d.ts

@@ -48,11 +48,7 @@ interface TValidatorPluginContext {
  * @typeParam T - The annotated type definition.
  * @typeParam DataType - The TypeScript type that `validate` narrows to (auto-inferred).
  */
-declare class Validator<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = T extends {
-    type: {
-        __dataType?: infer D;
-    };
-} ? unknown extends D ? T extends new (...args: any[]) => infer I ? I : unknown : D : unknown> {
+declare class Validator<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
     protected readonly def: T;
     protected opts: TValidatorOptions;
     constructor(def: T, opts?: Partial<TValidatorOptions>);
@@ -148,6 +144,26 @@ interface TAtscriptTypeFinal<DataType = unknown> {
 type InferDataType<T> = T extends {
     __dataType?: infer D;
 } ? D : unknown;
+/**
+ * Extract the DataType from a {@link TAtscriptAnnotatedType}.
+ *
+ * Resolves the phantom `__dataType` carried by the type definition.
+ * When `__dataType` is `unknown` (unset), falls back to the constructor
+ * instance type if `T` is also a class (i.e. a generated interface).
+ *
+ * @example
+ * ```ts
+ * import type { TAtscriptDataType } from '@atscript/typescript/utils'
+ * import MyInterface from './my-interface.as'
+ *
+ * type Data = TAtscriptDataType<typeof MyInterface>
+ * ```
+ */
+type TAtscriptDataType<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType> = T extends {
+    type: {
+        __dataType?: infer D;
+    };
+} ? unknown extends D ? T extends new (...args: any[]) => infer I ? I : unknown : D : unknown;
 /** Union of all possible type definition shapes. */
 type TAtscriptTypeDef<DataType = unknown> = TAtscriptTypeComplex<DataType> | TAtscriptTypeFinal<DataType> | TAtscriptTypeArray<DataType> | TAtscriptTypeObject<string, DataType>;
 /**
@@ -496,4 +512,4 @@ declare function serializeAnnotatedType(type: TAtscriptAnnotatedType, options?:
 declare function deserializeAnnotatedType(data: TSerializedAnnotatedType): TAtscriptAnnotatedType;
 
 export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType, throwFeatureDisabled };
-export type { InferDataType, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TCreateDataOptions, TFlattenOptions, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext, TValueResolver };
+export type { InferDataType, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptDataType, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TCreateDataOptions, TFlattenOptions, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext, TValueResolver };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Atscript: typescript-gen support.",
   "keywords": [
     "annotations",
@@ -64,7 +64,7 @@
     "vitest": "3.2.4"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.21"
+    "@atscript/core": "^0.1.23"
   },
   "build": [
     {},

package/skills/atscript-typescript/utilities.md

@@ -300,6 +300,55 @@ import { isPhantomType } from '@atscript/typescript/utils'
 isPhantomType(someProperty)  // true if designType === 'phantom'
 ```
 
+## `TAtscriptDataType<T>` — Extract DataType from Annotated Type
+
+Utility type that extracts the underlying data shape from a `TAtscriptAnnotatedType`. This is the primary way to obtain a TypeScript data type from an Atscript-generated class, especially useful in generic contexts.
+
+```ts
+import type { TAtscriptDataType } from '@atscript/typescript/utils'
+import { Product } from './product.as'
+
+type ProductData = TAtscriptDataType<typeof Product>
+// ProductData = { name: string; price: number; tags: string[] }
+```
+
+### How It Resolves
+
+1. Extracts the phantom `__dataType` from the type definition
+2. If `__dataType` is `unknown` (unset), falls back to the constructor's instance type (`T extends new (...) => infer I`)
+3. Otherwise returns `unknown`
+
+### Use in Generics
+
+`TAtscriptDataType` is designed for generic code that needs to derive data types from annotated type parameters:
+
+```ts
+import type { TAtscriptAnnotatedType, TAtscriptDataType } from '@atscript/typescript/utils'
+
+// Generic repository that infers its entity type
+class Repository<T extends TAtscriptAnnotatedType> {
+  findOne(id: string): Promise<TAtscriptDataType<T>> { /* ... */ }
+  insertOne(data: TAtscriptDataType<T>): Promise<void> { /* ... */ }
+}
+
+// Usage — DataType is automatically inferred
+const repo = new Repository<typeof Product>()
+const product = await repo.findOne('123') // typed as Product
+
+// Generic function
+function validate<T extends TAtscriptAnnotatedType>(
+  schema: T,
+  data: unknown
+): data is TAtscriptDataType<T> {
+  return schema.validator().validate(data, true)
+}
+```
+
+### Difference from `InferDataType`
+
+- `TAtscriptDataType<T>` — operates on `TAtscriptAnnotatedType` (the full annotated wrapper). Use this for generated classes and generic code.
+- `InferDataType<T>` — operates on raw type definitions (`TAtscriptTypeDef`, `TAtscriptTypeObject`, etc.). Lower-level, extracts `__dataType` from the type def's phantom generic directly.
+
 ## Type Exports
 
 Key types you may need to import:
@@ -315,7 +364,8 @@ import type {
   TAtscriptTypeComplex,           // union/intersection/tuple type def
   TMetadataMap,                   // typed metadata map
   TAnnotatedTypeHandle,           // fluent builder handle
-  InferDataType,                  // extract DataType from a type def
+  InferDataType,                  // extract DataType from a type def's phantom generic
+  TAtscriptDataType,              // extract DataType from TAtscriptAnnotatedType
   TValidatorOptions,              // validator config
   TValidatorPlugin,               // plugin function type
   TValidatorPluginContext,         // plugin context