@objectstack/spec 0.3.2 → 0.4.1

package/dist/api/odata.zod.d.ts

@@ -0,0 +1,482 @@
+import { z } from 'zod';
+/**
+ * OData v4 Protocol Support
+ *
+ * Open Data Protocol (OData) v4 is an industry-standard protocol for building
+ * and consuming RESTful APIs. It provides a uniform way to expose, structure,
+ * query, and manipulate data.
+ *
+ * ## Overview
+ *
+ * OData v4 provides standardized URL conventions for querying data including:
+ * - $select: Choose which fields to return
+ * - $filter: Filter results with complex expressions
+ * - $orderby: Sort results
+ * - $top/$skip: Pagination
+ * - $expand: Include related entities
+ * - $count: Get total count
+ *
+ * ## Use Cases
+ *
+ * 1. **Enterprise Integration**
+ *    - Integrate with Microsoft Dynamics 365
+ *    - Connect to SharePoint Online
+ *    - SAP OData services
+ *
+ * 2. **API Standardization**
+ *    - Provide consistent query interface
+ *    - Standard pagination and filtering
+ *    - Industry-recognized protocol
+ *
+ * 3. **External Data Sources**
+ *    - Connect to OData-compliant systems
+ *    - Federated queries
+ *    - Data virtualization
+ *
+ * @see https://www.odata.org/documentation/
+ * @see https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html
+ *
+ * @example OData Query
+ * ```
+ * GET /api/odata/customers?
+ *   $select=name,email&
+ *   $filter=country eq 'US' and revenue gt 100000&
+ *   $orderby=revenue desc&
+ *   $top=10&
+ *   $skip=20&
+ *   $expand=orders&
+ *   $count=true
+ * ```
+ *
+ * @example Programmatic Use
+ * ```typescript
+ * const query: ODataQuery = {
+ *   select: ['name', 'email'],
+ *   filter: "country eq 'US' and revenue gt 100000",
+ *   orderby: 'revenue desc',
+ *   top: 10,
+ *   skip: 20,
+ *   expand: ['orders'],
+ *   count: true
+ * }
+ * ```
+ */
+/**
+ * OData Query Options Schema
+ *
+ * System query options defined by OData v4 specification.
+ * These are URL query parameters that control the query execution.
+ *
+ * @see https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptions
+ */
+export declare const ODataQuerySchema: z.ZodObject<{
+    /**
+     * $select - Select specific fields to return
+     *
+     * Comma-separated list of field names to include in the response.
+     * Reduces payload size and improves performance.
+     *
+     * @example "name,email,phone"
+     * @example "id,customer/name" - With navigation path
+     */
+    $select: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    /**
+     * $filter - Filter results with conditions
+     *
+     * OData filter expression using comparison operators, logical operators,
+     * and functions.
+     *
+     * Comparison: eq, ne, lt, le, gt, ge
+     * Logical: and, or, not
+     * Functions: contains, startswith, endswith, length, indexof, substring, etc.
+     *
+     * @example "age gt 18"
+     * @example "country eq 'US' and revenue gt 100000"
+     * @example "contains(name, 'Smith')"
+     * @example "startswith(email, 'admin') and isActive eq true"
+     */
+    $filter: z.ZodOptional<z.ZodString>;
+    /**
+     * $orderby - Sort results
+     *
+     * Comma-separated list of fields with optional asc/desc.
+     * Default is ascending.
+     *
+     * @example "name"
+     * @example "revenue desc"
+     * @example "country asc, revenue desc"
+     */
+    $orderby: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    /**
+     * $top - Limit number of results
+     *
+     * Maximum number of results to return.
+     * Equivalent to SQL LIMIT or FETCH FIRST.
+     *
+     * @example 10
+     * @example 100
+     */
+    $top: z.ZodOptional<z.ZodNumber>;
+    /**
+     * $skip - Skip results for pagination
+     *
+     * Number of results to skip before returning results.
+     * Equivalent to SQL OFFSET.
+     *
+     * @example 20
+     * @example 100
+     */
+    $skip: z.ZodOptional<z.ZodNumber>;
+    /**
+     * $expand - Include related entities
+     *
+     * Comma-separated list of navigation properties to expand.
+     * Loads related data in the same request.
+     *
+     * @example "orders"
+     * @example "customer,products"
+     * @example "orders($select=id,total)" - With nested query options
+     */
+    $expand: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    /**
+     * $count - Include total count
+     *
+     * When true, includes totalResults count in response.
+     * Useful for pagination UI.
+     *
+     * @example true
+     */
+    $count: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * $search - Full-text search
+     *
+     * Free-text search expression.
+     * Search implementation is service-specific.
+     *
+     * @example "John Smith"
+     * @example "urgent AND support"
+     */
+    $search: z.ZodOptional<z.ZodString>;
+    /**
+     * $format - Response format
+     *
+     * Preferred response format.
+     *
+     * @example "json"
+     * @example "xml"
+     */
+    $format: z.ZodOptional<z.ZodEnum<["json", "xml", "atom"]>>;
+    /**
+     * $apply - Data aggregation
+     *
+     * Aggregation transformations (groupby, aggregate, etc.)
+     * Part of OData aggregation extension.
+     *
+     * @example "groupby((country),aggregate(revenue with sum as totalRevenue))"
+     */
+    $apply: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    $select?: string | string[] | undefined;
+    $filter?: string | undefined;
+    $orderby?: string | string[] | undefined;
+    $top?: number | undefined;
+    $skip?: number | undefined;
+    $expand?: string | string[] | undefined;
+    $count?: boolean | undefined;
+    $search?: string | undefined;
+    $format?: "json" | "xml" | "atom" | undefined;
+    $apply?: string | undefined;
+}, {
+    $select?: string | string[] | undefined;
+    $filter?: string | undefined;
+    $orderby?: string | string[] | undefined;
+    $top?: number | undefined;
+    $skip?: number | undefined;
+    $expand?: string | string[] | undefined;
+    $count?: boolean | undefined;
+    $search?: string | undefined;
+    $format?: "json" | "xml" | "atom" | undefined;
+    $apply?: string | undefined;
+}>;
+export type ODataQuery = z.infer<typeof ODataQuerySchema>;
+/**
+ * OData Filter Operator
+ *
+ * Standard comparison and logical operators in OData filter expressions.
+ */
+export declare const ODataFilterOperatorSchema: z.ZodEnum<["eq", "ne", "lt", "le", "gt", "ge", "and", "or", "not", "(", ")", "in", "has"]>;
+export type ODataFilterOperator = z.infer<typeof ODataFilterOperatorSchema>;
+/**
+ * OData Filter Function
+ *
+ * Standard functions available in OData filter expressions.
+ */
+export declare const ODataFilterFunctionSchema: z.ZodEnum<["contains", "startswith", "endswith", "length", "indexof", "substring", "tolower", "toupper", "trim", "concat", "year", "month", "day", "hour", "minute", "second", "date", "time", "now", "maxdatetime", "mindatetime", "round", "floor", "ceiling", "cast", "isof", "any", "all"]>;
+export type ODataFilterFunction = z.infer<typeof ODataFilterFunctionSchema>;
+/**
+ * OData Response Schema
+ *
+ * Standard OData JSON response format.
+ */
+export declare const ODataResponseSchema: z.ZodObject<{
+    /**
+     * OData context URL
+     * Describes the payload structure
+     */
+    '@odata.context': z.ZodOptional<z.ZodString>;
+    /**
+     * Total count (when $count=true)
+     */
+    '@odata.count': z.ZodOptional<z.ZodNumber>;
+    /**
+     * Next link for pagination
+     */
+    '@odata.nextLink': z.ZodOptional<z.ZodString>;
+    /**
+     * Result array
+     */
+    value: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">;
+}, "strip", z.ZodTypeAny, {
+    value: Record<string, any>[];
+    '@odata.context'?: string | undefined;
+    '@odata.count'?: number | undefined;
+    '@odata.nextLink'?: string | undefined;
+}, {
+    value: Record<string, any>[];
+    '@odata.context'?: string | undefined;
+    '@odata.count'?: number | undefined;
+    '@odata.nextLink'?: string | undefined;
+}>;
+export type ODataResponse = z.infer<typeof ODataResponseSchema>;
+/**
+ * OData Error Response Schema
+ *
+ * Standard OData error format.
+ */
+export declare const ODataErrorSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        /**
+         * Error code
+         */
+        code: z.ZodString;
+        /**
+         * Error message
+         */
+        message: z.ZodString;
+        /**
+         * Target of the error (field name, etc.)
+         */
+        target: z.ZodOptional<z.ZodString>;
+        /**
+         * Additional error details
+         */
+        details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            target: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            message: string;
+            code: string;
+            target?: string | undefined;
+        }, {
+            message: string;
+            code: string;
+            target?: string | undefined;
+        }>, "many">>;
+        /**
+         * Inner error for debugging
+         */
+        innererror: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        code: string;
+        target?: string | undefined;
+        details?: {
+            message: string;
+            code: string;
+            target?: string | undefined;
+        }[] | undefined;
+        innererror?: Record<string, any> | undefined;
+    }, {
+        message: string;
+        code: string;
+        target?: string | undefined;
+        details?: {
+            message: string;
+            code: string;
+            target?: string | undefined;
+        }[] | undefined;
+        innererror?: Record<string, any> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    error: {
+        message: string;
+        code: string;
+        target?: string | undefined;
+        details?: {
+            message: string;
+            code: string;
+            target?: string | undefined;
+        }[] | undefined;
+        innererror?: Record<string, any> | undefined;
+    };
+}, {
+    error: {
+        message: string;
+        code: string;
+        target?: string | undefined;
+        details?: {
+            message: string;
+            code: string;
+            target?: string | undefined;
+        }[] | undefined;
+        innererror?: Record<string, any> | undefined;
+    };
+}>;
+export type ODataError = z.infer<typeof ODataErrorSchema>;
+/**
+ * OData Metadata Configuration
+ *
+ * Configuration for OData metadata endpoint ($metadata).
+ */
+export declare const ODataMetadataSchema: z.ZodObject<{
+    /**
+     * Service namespace
+     */
+    namespace: z.ZodString;
+    /**
+     * Entity types to expose
+     */
+    entityTypes: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        key: z.ZodArray<z.ZodString, "many">;
+        properties: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            nullable: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            type: string;
+            name: string;
+            nullable: boolean;
+        }, {
+            type: string;
+            name: string;
+            nullable?: boolean | undefined;
+        }>, "many">;
+        navigationProperties: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            partner: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: string;
+            name: string;
+            partner?: string | undefined;
+        }, {
+            type: string;
+            name: string;
+            partner?: string | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        properties: {
+            type: string;
+            name: string;
+            nullable: boolean;
+        }[];
+        key: string[];
+        navigationProperties?: {
+            type: string;
+            name: string;
+            partner?: string | undefined;
+        }[] | undefined;
+    }, {
+        name: string;
+        properties: {
+            type: string;
+            name: string;
+            nullable?: boolean | undefined;
+        }[];
+        key: string[];
+        navigationProperties?: {
+            type: string;
+            name: string;
+            partner?: string | undefined;
+        }[] | undefined;
+    }>, "many">;
+    /**
+     * Entity sets
+     */
+    entitySets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        entityType: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        entityType: string;
+    }, {
+        name: string;
+        entityType: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    namespace: string;
+    entityTypes: {
+        name: string;
+        properties: {
+            type: string;
+            name: string;
+            nullable: boolean;
+        }[];
+        key: string[];
+        navigationProperties?: {
+            type: string;
+            name: string;
+            partner?: string | undefined;
+        }[] | undefined;
+    }[];
+    entitySets: {
+        name: string;
+        entityType: string;
+    }[];
+}, {
+    namespace: string;
+    entityTypes: {
+        name: string;
+        properties: {
+            type: string;
+            name: string;
+            nullable?: boolean | undefined;
+        }[];
+        key: string[];
+        navigationProperties?: {
+            type: string;
+            name: string;
+            partner?: string | undefined;
+        }[] | undefined;
+    }[];
+    entitySets: {
+        name: string;
+        entityType: string;
+    }[];
+}>;
+export type ODataMetadata = z.infer<typeof ODataMetadataSchema>;
+/**
+ * Helper functions for OData operations
+ */
+export declare const OData: {
+    /**
+     * Build OData query URL
+     */
+    readonly buildUrl: (baseUrl: string, query: ODataQuery) => string;
+    /**
+     * Create a simple filter expression
+     */
+    readonly filter: {
+        readonly eq: (field: string, value: string | number | boolean) => string;
+        readonly ne: (field: string, value: string | number | boolean) => string;
+        readonly gt: (field: string, value: number) => string;
+        readonly lt: (field: string, value: number) => string;
+        readonly contains: (field: string, value: string) => string;
+        readonly and: (...expressions: string[]) => string;
+        readonly or: (...expressions: string[]) => string;
+    };
+};
+//# sourceMappingURL=odata.zod.d.ts.map

package/dist/api/odata.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odata.zod.d.ts","sourceRoot":"","sources":["../../src/api/odata.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;;;;;;OAQG;;IAMH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;OASG;;IAMH;;;;;;;;OAQG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;;OASG;;IAMH;;;;;;;OAOG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;OAOG;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,4FAqBpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,iSAsCpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC9B;;;OAGG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;QAEzB;;WAEG;;QAGH;;WAEG;;QAGH;;WAEG;;QAGH;;WAEG;;;;;;;;;;;;;;QAOH;;WAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGL,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;IAC9B;;OAEG;;IAGH;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAgBH;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKH,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,KAAK;IAChB;;OAEG;iCACiB,MAAM,SAAS,UAAU,KAAG,MAAM;IAsCtD;;OAEG;;6BAEW,MAAM,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO;6BAExC,MAAM,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO;6BAExC,MAAM,SAAS,MAAM;6BACrB,MAAM,SAAS,MAAM;mCACf,MAAM,SAAS,MAAM;uCACjB,MAAM,EAAE;sCACT,MAAM,EAAE;;CAEvB,CAAC"}