shanegh / magic-odata Goto Github PK

View Code? Open in Web Editor NEW

0.0 2.0 0.0 851 KB

Magical OData client generation for typescript

License: MIT License

PowerShell 0.73% TypeScript 90.52% C# 7.67% HTML 0.04% CSS 0.01% Batchfile 0.01% JavaScript 0.82% Shell 0.21%

browser nodejs odata odata-client odatav4 typescript generate-code

magic-odata's Introduction

magic-odata

Magical OData client generation for typescript. No more string. No more any!

Install

npm i magic-odata-code-gen --save-dev; npm i magic-odata-client;

magic-odata-code-gen is a dev dependency required to generate a client at compile time
- This tool is small and we recommend installing it locally per project in order to avoid versioning issues
magic-odata-client is a dependency of your application. The generated code will use this package

Generate

node node_modules/magic-odata-code-gen/dist/index.js --metadataUrl "https://raw.githubusercontent.com/ShaneGH/magic-odata/main/docs/sampleOdataMetadata.xml"

Use

// import a generated client
import { ODataClient } from "./odataClient.js"

// create a client instance
const oDataClient = new ODataClient({
    // inject a basic Http client
    request: (input, init) => fetch(input, init),

    // add a root URI
    uriRoot: "https://my.odata.server/odata"
})

// use the client!
const popularBlogPosts = oDataClient.BlogPosts
    // Use object deconstruction to choose query tools
    .withQuery((blogPost, {
        $orderby: {orderBy}, 
        $skip, 
        $top
    }) => [ 
        // Combine query tools and fluent operations to build a query
        blogPost.Comments.$count.gt(100).or(blogPost.Likes.gt(100)),
        orderBy(blogPost.Name),
        $skip(0),
        $top(10)
    ])
    .get();

Why?

Write safe, statically typed odata queries in typescript. No more string. No more any!

Cut down on runtime errors
Explore OData API possibilities in your IDE
Runs in the browser or in node
No prod dependencies. Small bundle size
- Generated executable code is tiny. Almost all generated code is type information
- magic-odata-client minifies and compresses to ~10KB
Optional angular mode, for the angular HttpClient

Features

See Features.md

Code gen configuration
- $metadata files protected with authentication
- Angular mode
Client configuration
OData GET requests
OData URI generation
Entity keys
Entity path
@Parameter aliases
Enums
Functions
Indexed ordered collections
Query options
- $filter
  - fluent comparison operators
- $select
- $expand
  - $levels
- $orderBy
- $search
- $skip, $top and $count
- custom
- $root
Casting
$value

Contributing

See Contributing.md

magic-odata's People

Contributors

Watchers

magic-odata's Issues

Add namespaces to enums

Should be configurable per http client or client call. The code to add namespaces is:

Serialize enums with their full value

add a setting to switch back to just serializing the enum name

$value request

new ODataClient(...).Users.withKey(x).subPath(x => x.Name).subPath(x => x.$value)

Alternative

Hi,
I'm really unsure if I should open this ticket, but here I go.
I'm the author of odata2ts. And it actually does what magic-odata does. Have you considered this as alternative?

Don't get me wrong: It's always cool to have alternatives and there also exist quite different reasons to have them. But since I know how long the road is to generate a full featured OData client (nearly impossible 😉)...

Anyways, I hope I don't step on your toes by writing this.

But then again, I'm curious and if you have considered it as alternative and wanted to have a different tool, then I would be highly interested in those reasons.

Add missing functions (p1)

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_BuiltinQueryFunctions

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_TypeFunctions
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_GeoFunctions

String and Collection Functions (collection versions only)
Collection Functions
Type Functions
Geo Functions

Generate from $metadata local file: file path is not relative to config file

File path should be relative to config file

User can do illegal queries on singletons

EntitySet.withQuery when the current entity is a singleton has all of the same functionality as an entity Collection

From ASPNET:
The requested resource is not a collection. Query options $filter, $orderby, $count, $skip, and $top can be applied only on collections

Add missing data types

Search for this issue in code

Simple and ref Parameter aliases

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ParameterAliases

Negation

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_Negation

tests
tests for negation in offset

All client get requests can return null

Need to take this into account in type system somehow

Complex sub paths

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_AddressingaSubsetofaCollection
Examples:

Add test for cast entity name, if name contains namesapace

Casting tests all look like this:

await client.HasIds
    .withKey(x => x.key(user.Id!))
    .cast(i => i.Blog())
    .get()

Need a test like this

await client.HasIds
    .withKey(x => x.key(user.Id!))
    .cast(i => i.My_Odata_Entities_Blog())
    .get()

Expose query builder, detached from Entityset

const queryParts = userQuery((user, {filter: {eq}}) => eq(user.id, 123))
console.log(queryParts.$filter)

Also, remove exposed buildComplexTypeRef from magic-odata-client index.ts

ODataServiceConfig is not organised correctly

EntityCollections should be inside Namespaces, not parallel with

Add missing functions (p0)

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_BuiltinQueryFunctions
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_indexof

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_length
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_substring collections
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_CollectionFunctions
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_StringFunctions
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_DateandTimeFunctions
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_ArithmeticFunctions
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_ConditionalFunctions

Date and Time Functions
Conditional Functions

Compatibility with verbatimModuleSyntax

The compile option verbatimModuleSyntax was added in TypeScript 5.0.
If this option is true, imports of types that are not used in the code or only used as type names will fail without the type modifier.

At the top of the generated OData Client code, many types are imported, including those that are not used.
To avoid compile errors, could you please make sure that unused types are not imported, or add the type modifier appropriately?

Fix integer based enums in query data params

Search for this text: NOTE: enum values where the enum is represented by a number in typescript are currently not supported. Use createRawConst instead

Search for this issue

Notes:
The issue is that the "Const" ParameterDefinition returned by createConst does not have any type info. The only way I can see at the moment is to mutate it after generation in multiple places in code.

In key lookup, where the key type is known
In function calls where the function type is known
In query parts, using the type that it is being compared against

None of this is ideal and would be susceptible to bugs

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_AddressingaMemberofanOrderedCollecti

Whitelisted types should automatically whitelist their properties

Whitelisted types should automatically whitelist their Complex object and Enum properties (but not navigation properties)

e.g. in test framework

Whitelist User should auto whitelist UserType
Whitelist Comment should auto whitelist Tag
Whitelist Blog should not whitelist User or BlogPost

GeographyPoint = "GeographyPoint",
GeographyLineString = "GeographyLineString",
GeographyPolygon = "GeographyPolygon",
GeographyMultiPoint = "GeographyMultiPoint",
GeographyMultiLineString = "GeographyMultiLineString",
GeographyMultiPolygon = "GeographyMultiPolygon",
GeographyCollection = "GeographyCollection",
GeometryPoint = "GeometryPoint",
GeometryLineString = "GeometryLineString",
GeometryPolygon = "GeometryPolygon",
GeometryMultiPoint = "GeometryMultiPoint",
GeometryMultiLineString = "GeometryMultiLineString",
GeometryMultiPolygon = "GeometryMultiPolygon",
GeometryCollection = "GeometryCollection",

Primitive literals

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_PrimitiveLiterals

$this, $it, $root

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_it
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_this
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_root

subPathRaw function

const comment = await client.BlogPosts
    .withKey(x => x.keyRaw(`'${user.blogPost.Id}'`))
    .subPathRaw("Comments") // something like this. The interface needs to be decided
    .withKey(x => x.key(user.comment.Id!, WithKeyType.PathSegment))
    .get();

or
and
eq
ne
gt
lt
ge
le
isIn

Functions can be used within $filter or $orderby system query options my/items?$filter=eq($it/GetId(), 123)
Functions can be used within $filter or $orderby system query options my/items?$filter=eq($root/GetPrimaryObj()/Id, 123)
http://host/service/Customers?$filter=Sales.SalesRegion(City=$it/City) eq 'Western'

Functions

http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_Functions
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_BindinganOperationtoaResource
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ActionFunctionExtensibility
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_AddressingFunctions
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_AddressingEachMemberofaCollection
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_ComplexandCollectionLiterals

https://learn.microsoft.com/en-us/aspnet/web-api/overview/odata-support-in-aspnet-web-api/odata-v4/odata-actions-and-functions

Linked: ShaneGH/magic-odata-features#30

1. Allow proper querying after a $count

client.Users.subPath(x => x.$count).withQuery(...)

2. Allow proper querying after a $value

client.Users.withKey(123).subPath(x => x.namr).subPath(x => x.$value).withQuery(...)

3. Disallow path/cast after query

client.Users.withKey(123).withQuery(...).subPath(x => x.Blogs)