@atscript/typescript 0.1.33 → 0.1.35

package/dist/utils.d.ts

@@ -103,6 +103,10 @@ declare class ValidatorError extends Error {
 declare function createAnnotatedTypeNode(type: TAtscriptTypeDef, metadata: TMetadataMap<AtscriptMetadata>, opts?: {
     id?: string;
     optional?: boolean;
+    ref?: {
+        type: () => TAtscriptAnnotatedType;
+        field: string;
+    };
 }): TAtscriptAnnotatedType;
 /** Type definition for union, intersection, or tuple types. */
 interface TAtscriptTypeComplex<DataType = unknown> {
@@ -191,6 +195,10 @@ interface TAtscriptAnnotatedType<T extends TAtscriptTypeDef = TAtscriptTypeDef,
     metadata: TMetadataMap<AtscriptMetadata>;
     optional?: boolean;
     id?: string;
+    ref?: {
+        type: () => TAtscriptAnnotatedType;
+        field: string;
+    };
 }
 /** An annotated type that is also a class constructor (i.e. a generated interface class). */
 type TAtscriptAnnotatedTypeConstructor = TAtscriptAnnotatedType & (new (...args: any[]) => any);
@@ -234,7 +242,10 @@ declare function defineAnnotatedType(_kind?: TKind, base?: any): TAnnotatedTypeH
  */
 interface TMetadataMap<O extends object> extends Map<keyof O, O[keyof O]> {
     get<K extends keyof O>(key: K): O[K] | undefined;
+    get(key: string): unknown;
     set<K extends keyof O>(key: K, value: O[K]): this;
+    has<K extends keyof O>(key: K): boolean;
+    has(key: string): boolean;
 }
 /** Fluent builder handle returned by {@link defineAnnotatedType}. */
 interface TAnnotatedTypeHandle {
@@ -252,9 +263,11 @@ interface TAnnotatedTypeHandle {
     propPattern(pattern: RegExp, value: TAtscriptAnnotatedType): TAnnotatedTypeHandle;
     optional(value?: boolean): TAnnotatedTypeHandle;
     copyMetadata(fromMetadata: TMetadataMap<AtscriptMetadata>): TAnnotatedTypeHandle;
-    refTo(type: TAtscriptAnnotatedType & {
+    refTo(type: (TAtscriptAnnotatedType & {
+        name?: string;
+    }) | (() => TAtscriptAnnotatedType & {
         name?: string;
-    }, chain?: string[]): TAnnotatedTypeHandle;
+    }), chain?: string[]): TAnnotatedTypeHandle;
     annotate(key: keyof AtscriptMetadata, value: any, asArray?: boolean): TAnnotatedTypeHandle;
     id(value: string): TAnnotatedTypeHandle;
 }
@@ -362,7 +375,7 @@ interface TCreateDataOptions {
      * - `'empty'` — structural defaults only (`''`, `0`, `false`, `[]`, `{}`); optional props skipped
      * - `'default'` — use `@meta.default` annotations; optional props skipped unless annotated
      * - `'example'` — use `@meta.example` annotations; optional props always included; arrays get one sample item
-     * - `'db'` — use `@db.default.value` (parsed) or `@db.default.fn` (returns fn name string); optional props skipped unless annotated
+     * - `'db'` — use `@db.default` (parsed) or `@db.default.fn` (returns fn name string); optional props skipped unless annotated
      * - `function` — custom resolver per field; optional props skipped unless resolver returns a value
      *
      * @default 'empty'
@@ -376,7 +389,7 @@ interface TCreateDataOptions {
  * - `'empty'` — structural defaults only; optional props omitted
  * - `'default'` — uses `@meta.default` annotations; optional props omitted unless annotated
  * - `'example'` — uses `@meta.example` annotations; optional props always included; arrays get one sample item
- * - `'db'` — uses `@db.default.value` (parsed) or `@db.default.fn` (fn name string); optional props omitted unless annotated
+ * - `'db'` — uses `@db.default` (parsed) or `@db.default.fn` (fn name string); optional props omitted unless annotated
  * - `function` — custom resolver; optional props omitted unless resolver returns a value
  *
  * When a `@meta.default` / `@meta.example` value is set on a complex type (object, array)
@@ -436,6 +449,31 @@ interface TFlattenOptions {
  */
 declare function flattenAnnotatedType(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, options?: TFlattenOptions): Map<string, TAtscriptAnnotatedType>;
 
+/** Runtime shape of a ref annotation argument (lazy type reference with optional chain). */
+type AtscriptRef = {
+    type: () => TAtscriptAnnotatedType;
+    field: string;
+} | (() => TAtscriptAnnotatedType);
+/** Field reference within a query expression. */
+interface AtscriptQueryFieldRef {
+    type?: () => TAtscriptAnnotatedType;
+    field: string;
+}
+/** Single comparison in a query expression. */
+interface AtscriptQueryComparison {
+    left: AtscriptQueryFieldRef;
+    op: string;
+    right?: AtscriptQueryFieldRef | unknown[] | unknown;
+}
+/** Query expression tree (recursive). */
+type AtscriptQueryNode = AtscriptQueryComparison | {
+    $and: AtscriptQueryNode[];
+} | {
+    $or: AtscriptQueryNode[];
+} | {
+    $not: AtscriptQueryNode;
+};
+
 /** Current serialization format version. Bumped on breaking changes to the serialized shape. */
 declare const SERIALIZE_VERSION = 1;
 /** Top-level serialized annotated type. JSON-safe representation of a {@link TAtscriptAnnotatedType}. */
@@ -478,7 +516,11 @@ interface TSerializedTypeComplex {
     items: TSerializedAnnotatedTypeInner[];
     tags: string[];
 }
-type TSerializedTypeDef = TSerializedTypeFinal | TSerializedTypeObject | TSerializedTypeArray | TSerializedTypeComplex;
+interface TSerializedTypeRef {
+    kind: '$ref';
+    id: string;
+}
+type TSerializedTypeDef = TSerializedTypeFinal | TSerializedTypeObject | TSerializedTypeArray | TSerializedTypeComplex | TSerializedTypeRef;
 /** Context passed to {@link TSerializeOptions.processAnnotation} for each annotation entry. */
 interface TProcessAnnotationContext {
     /** Annotation key, e.g. "meta.label" */
@@ -565,6 +607,22 @@ type FlatOf<T> = T extends {
 type PrimaryKeyOf<T> = T extends {
     __pk: infer PK;
 } ? PK : unknown;
+/**
+ * Extracts the own-props flat map from an Atscript annotated type.
+ * `__ownProps` contains only table-owned fields (no navigation property descendants).
+ * Falls back to `FlatOf<T>` for types generated before this feature was added.
+ */
+type OwnPropsOf<T> = T extends {
+    __ownProps: infer O;
+} ? O : FlatOf<T>;
+/**
+ * Extracts the navigation property map from an Atscript annotated type.
+ * `__navProps` maps nav prop names to their declared types (e.g., `{ author: Author, comments: Comment[] }`).
+ * Returns `Record<string, never>` when no `__navProps` exists (no nav props or pre-feature type).
+ */
+type NavPropsOf<T> = T extends {
+    __navProps: infer N extends Record<string, unknown>;
+} ? N : Record<string, never>;
 
 export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, cloneRefProp, createAnnotatedTypeNode, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, mergeJsonSchemas, serializeAnnotatedType, throwFeatureDisabled };
-export type { FlatOf, InferDataType, PrimaryKeyOf, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptDataType, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TCreateDataOptions, TFlattenOptions, TJsonSchema, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext, TValueResolver };
+export type { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryNode, AtscriptRef, FlatOf, InferDataType, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptDataType, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TCreateDataOptions, TFlattenOptions, TJsonSchema, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext, TValueResolver };