angular-odata 0.161.0 → 0.163.0

package/README.md

@@ -1,16 +1,18 @@
 <h1 align="center">Angular OData</h1>
 
 <p align="center">
-  <em>A fluent API for querying, creating, updating and deleting OData resources in Angular.</em>
+  <em>A typed, fluent client for OData services in Angular.</em>
   <br>
 </p>
 
 <p align="center">
-  <a href="CONTRIBUTING.md">Contributing</a>
+  <a href="https://diegomvh.github.io/angular-odata/docs/api/additional-documentation/introduction.html">Handbook</a>
   ·
-  <a href="./docs/api/index.html">Documentation</a>
+  <a href="https://diegomvh.github.io/angular-odata/docs/api/index.html">API reference</a>
   ·
   <a href="https://github.com/diegomvh/AngularODataEntity">Demo</a>
+  ·
+  <a href="https://github.com/diegomvh/angular-odata/blob/main/CONTRIBUTING.md">Contributing</a>
   <br>
   <br>
 </p>
@@ -26,14 +28,170 @@
 
 <hr>
 
-## Installation
+[OData](https://www.odata.org/) is a standard for REST APIs: every service describes its
+data in a `$metadata` document and accepts the same query options (`$filter`, `$select`,
+`$expand`, `$orderby`, …). **angular-odata** lets your Angular application talk to any OData
+service without writing URLs by hand: you build requests with typed TypeScript code and get
+back typed results.
+
+```typescript
+// GET People?$select=UserName,FirstName&$filter=contains(UserName, 'russell')&$top=10
+client
+  .entitySet<Person>('People')
+  .query((q) => {
+    q.filter(({ e, t }) => e().contains(t.UserName, 'russell'));
+    q.select(['UserName', 'FirstName']);
+    q.top(10);
+  })
+  .fetch()
+  .subscribe(({ entities }) => console.log(entities));
+```
+
+## Features
+
+- **Typed query builder**: `$filter`, `$select`, `$expand`, `$orderby`, `$search`,
+  `$compute`, `$apply` and paging, with field names checked by the compiler.
+- **Complete OData API**: entity sets, entities, navigation properties, functions,
+  actions, singletons, media and `$batch` requests.
+- **Code generation**: one command creates interfaces, services and models from your
+  service's `$metadata`.
+- **Models and collections**: change tracking, validation and `save()` / `destroy()`.
+- **Caching**: in-memory, Web Storage or IndexedDB, with fetch policies such as
+  `cache-first` and `cache-and-network`.
+- **Several APIs** in the same application, each with its own configuration.
 
-Install from npm:
+## Quick start
+
+### 1. Install
 
 ```bash
 npm i angular-odata
 ```
 
-## OData Version
+### 2. Register the client
+
+```typescript
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideODataClient } from 'angular-odata';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideODataClient({
+      config: { serviceRootUrl: 'https://services.odata.org/V4/TripPinServiceRW/' },
+    }),
+  ],
+};
+```
+
+Applications that use NgModules can import `ODataModule.forRoot({ config })` instead.
+
+### 3. Query your service
+
+```typescript
+import { Component, inject, signal } from '@angular/core';
+import { ODataClient } from 'angular-odata';
+
+interface Person {
+  UserName: string;
+  FirstName: string;
+  LastName: string;
+}
+
+@Component({
+  selector: 'app-people',
+  template: `
+    @for (person of people(); track person.UserName) {
+      <p>{{ person.FirstName }} {{ person.LastName }}</p>
+    }
+  `,
+})
+export class PeopleComponent {
+  private client = inject(ODataClient);
+  people = signal<Person[]>([]);
+
+  ngOnInit() {
+    this.client
+      .entitySet<Person>('People')
+      .query((q) => {
+        q.orderBy('LastName');
+        q.top(10);
+      })
+      .fetch()
+      .subscribe(({ entities }) => this.people.set(entities ?? []));
+  }
+}
+```
+
+### 4. Optional: generate a typed API
+
+Instead of writing interfaces and services by hand, generate them from the `$metadata` of
+your service:
+
+```bash
+ng generate angular-odata:apigen --name=TripPin --metadata='https://services.odata.org/V4/TripPinServiceRW/$metadata'
+```
+
+```typescript
+import { PeopleService, TripPinConfig } from './trip-pin';
+
+// app.config.ts
+provideODataClient({ config: TripPinConfig });
+
+// Any component or service
+const people = inject(PeopleService);
+people
+  .entity('russellwhyte')
+  .fetch()
+  .subscribe(({ entity }) => console.log(entity));
+```
+
+## A few more examples
+
+```typescript
+const people = client.entitySet<Person>('People');
+
+// Create, update and delete
+people.create({ UserName: 'jdoe', FirstName: 'John', LastName: 'Doe' }).subscribe();
+people.entity('jdoe').modify({ FirstName: 'Johnny' }).subscribe();
+people.entity('jdoe').destroy().subscribe();
+
+// Expand related entities: $expand=Trips($select=Name,Budget)
+people
+  .entity('russellwhyte')
+  .query((q) =>
+    q.expand(({ e, t }) =>
+      e().field(t.Trips, (f) => f.select(({ e, t }) => e().field(t.Name).field(t.Budget))),
+    ),
+  )
+  .fetch()
+  .subscribe(({ entity }) => console.log(entity?.Trips));
+
+// Follow the server's next links and get every entity
+people.fetchAll().subscribe(({ entities }) => console.log(entities.length));
+```
+
+## Documentation
+
+- **[Handbook](https://diegomvh.github.io/angular-odata/docs/api/additional-documentation/introduction.html)**:
+  guides for configuration, resources, the query builder, services, models, caching and code
+  generation.
+- **[API reference](https://diegomvh.github.io/angular-odata/docs/api/index.html)**: every
+  class and method, generated from the source code.
+- **[Demo application](https://github.com/diegomvh/AngularODataEntity)**: a complete Angular
+  application that uses the TripPin and Northwind sample services.
+
+## Compatibility
+
+- **Angular**: 20 or later.
+- **OData**: version 4 is fully supported; versions 3 and 2 have basic support.
+
+## Contributing
+
+Bug reports and pull requests are welcome. Read the
+[contributing guide](https://github.com/diegomvh/angular-odata/blob/main/CONTRIBUTING.md)
+to get started.
+
+## License
 
-The library works mainly with OData Version 4, however, it incorporates basic support for versions 3 and 2.
+[MIT](https://github.com/diegomvh/angular-odata/blob/main/LICENSE)

package/fesm2022/angular-odata.mjs

@@ -1593,7 +1593,7 @@ const Objects = {
     },
     resolveKey(key, { single = true } = {}) {
         const type = Types.rawType(key);
-        if (['number', 'string'].indexOf(type) !== -1)
+        if (['Number', 'String'].indexOf(type) !== -1)
             return key;
         if (type !== 'Map' && type !== 'Object') {
             return undefined;
@@ -3214,7 +3214,7 @@ class ODataSchema extends ODataAnnotatable {
         this.containers = (config.containers ?? []).map((config) => new ODataEntityContainer(config, this));
     }
     isNamespaceOf(type) {
-        return type.startsWith(this.namespace) ?? (this.alias && type.startsWith(this.alias));
+        return type.startsWith(this.namespace) || (this.alias != null && type.startsWith(this.alias));
     }
     get entitySets() {
         return this.containers.reduce((acc, container) => [...acc, ...container.entitySets], []);
@@ -5998,8 +5998,7 @@ class ODataRequest {
         if (apiOptions.prefer?.maxPageSize !== undefined && ['GET'].indexOf(this._method) !== -1)
             prefer.push(`odata.maxpagesize=${apiOptions.prefer?.maxPageSize}`);
         // Annotations
-        if (apiOptions.prefer?.includeAnnotations !== undefined &&
-            ['GET'].indexOf(this._method) !== -1)
+        if (apiOptions.prefer?.includeAnnotations !== undefined && ['GET'].indexOf(this._method) !== -1)
             prefer.push(`odata.include-annotations=${apiOptions.prefer?.includeAnnotations}`);
         // Omit Null Values
         if (apiOptions.prefer?.omitNullValues === true && ['GET'].indexOf(this._method) !== -1)
@@ -8148,18 +8147,25 @@ class CsdlRecord {
     }
 }
 class CsdlPropertyValue {
-    Name;
+    Property;
+    Bool;
     String;
     Date;
     EnumMember;
-    constructor({ Name, String, Date, EnumMember, }) {
-        this.Name = Name;
+    TextContent;
+    constructor({ Property, Bool, String, Date, EnumMember, TextContent, }) {
+        this.Property = Property;
+        this.Bool = Bool;
         this.String = String;
         this.Date = Date;
         this.EnumMember = EnumMember?.map((a) => new CsdlEnumMember(a));
+        this.TextContent = TextContent;
     }
     toJson() {
-        const json = { Name: this.Name };
+        const json = { Property: this.Property };
+        if (this.Bool !== undefined) {
+            json['Bool'] = this.Bool;
+        }
         if (this.String !== undefined) {
             json['String'] = this.String;
         }
@@ -8169,10 +8175,16 @@ class CsdlPropertyValue {
         if (Array.isArray(this.EnumMember) && this.EnumMember.length > 0) {
             json['EnumMember'] = this.EnumMember.map((m) => m.toJson());
         }
+        if (this.TextContent !== undefined) {
+            json['TextContent'] = this.TextContent;
+        }
         return json;
     }
     toConfig() {
-        const config = { name: this.Name };
+        const config = { property: this.Property };
+        if (this.Bool !== undefined) {
+            config['bool'] = this.Bool;
+        }
         if (this.String !== undefined) {
             config['string'] = this.String;
         }
@@ -8182,6 +8194,9 @@ class CsdlPropertyValue {
         if (Array.isArray(this.EnumMember) && this.EnumMember.length > 0) {
             config['enumMembers'] = this.EnumMember.map((m) => m.toConfig());
         }
+        if (this.TextContent !== undefined) {
+            config['textContent'] = this.TextContent;
+        }
         return config;
     }
 }
@@ -8402,10 +8417,8 @@ class CsdlEnumType extends CsdlAnnotable {
         return {
             ...super.toConfig(),
             name: this.Name,
-            fields: this.Member.reduce((acc, m) => ({
-                ...acc,
-                [m.Name]: m.toConfig(),
-            }), {}),
+            fields: this.Member.reduce((acc, m) => ({ ...acc, [m.Name]: m.toConfig(), }), {}),
+            members: this.Member.reduce((acc, m) => ({ ...acc, [m.Name]: m.Value, [m.Value]: m.Name }), {}),
             flags: this.IsFlags,
         };
     }
@@ -8426,11 +8439,11 @@ class CsdlMember extends CsdlAnnotable {
         return json;
     }
     toConfig(base) {
-        const config = {
+        return {
             ...super.toConfig(),
+            name: this.Name,
             value: this.Value,
         };
-        return config;
     }
 }
 
@@ -8447,12 +8460,15 @@ class CsdlStructuralProperty extends CsdlAnnotable {
         this.Type = this.Collection ? Type.substring(11, Type.length - 1) : Type;
     }
     toJson() {
-        return {
+        const json = {
             ...super.toJson(),
             Name: this.Name,
-            Type: this.Collection ? `Collection(${this.Type})` : this.Type,
-            Nullable: this.Nullable,
+            Type: this.Collection ? `Collection(${this.Type})` : this.Type
         };
+        if (this.Nullable !== undefined) {
+            json['Nullable'] = this.Nullable;
+        }
+        return json;
     }
 }
 class CsdlProperty extends CsdlStructuralProperty {
@@ -8795,7 +8811,7 @@ class CsdlFunction extends CsdlCallable {
             entitySetPath: this.EntitySetPath,
             bound: this.IsBound,
             composable: this.IsComposable,
-            parameters: this.Parameter?.map((p) => p.toConfig()),
+            parameters: this.Parameter?.reduce((acc, p) => ({ ...acc, [p.Name]: p.toConfig() }), {}),
             return: this.ReturnType?.toConfig(),
         };
     }
@@ -8814,7 +8830,7 @@ class CsdlAction extends CsdlCallable {
             name: this.Name,
             entitySetPath: this.EntitySetPath,
             bound: this.IsBound,
-            parameters: this.Parameter?.map((p) => p.toConfig()),
+            parameters: this.Parameter?.reduce((acc, p) => ({ ...acc, [p.Name]: p.toConfig() }), {}),
             return: this.ReturnType?.toConfig(),
         };
     }
@@ -8881,24 +8897,51 @@ class CsdlParameter extends CsdlAnnotable {
         this.SRID = SRID;
     }
     toJson() {
-        return {
+        const json = {
             ...super.toJson(),
             Name: this.Name,
-            Type: this.Collection ? `Collection(${this.Type})` : this.Type,
-            Nullable: this.Nullable,
-            MaxLength: this.MaxLength,
-            Precision: this.Precision,
-            Scale: this.Scale,
-            SRID: this.SRID,
+            Type: this.Collection ? `Collection(${this.Type})` : this.Type
         };
+        if (this.Nullable !== undefined) {
+            json['Nullable'] = this.Nullable;
+        }
+        if (this.MaxLength !== undefined) {
+            json['MaxLength'] = this.MaxLength;
+        }
+        if (this.Precision !== undefined) {
+            json['Precision'] = this.Precision;
+        }
+        if (this.Scale !== undefined) {
+            json['Scale'] = this.Scale;
+        }
+        if (this.SRID !== undefined) {
+            json['SRID'] = this.SRID;
+        }
+        return json;
     }
     toConfig() {
-        return {
+        const config = {
             ...super.toConfig(),
+            name: this.Name,
             type: this.Type,
-            nullable: this.Nullable,
-            collection: false,
+            collection: this.Collection,
         };
+        if (this.Nullable !== undefined) {
+            config.nullable = this.Nullable;
+        }
+        if (this.MaxLength !== undefined) {
+            config.maxLength = this.MaxLength;
+        }
+        if (this.Precision !== undefined) {
+            config.precision = this.Precision;
+        }
+        if (this.Scale !== undefined) {
+            config.scale = this.Scale;
+        }
+        if (this.SRID !== undefined) {
+            config.srid = this.SRID;
+        }
+        return config;
     }
 }
 class CsdlReturnType {
@@ -8919,20 +8962,47 @@ class CsdlReturnType {
         this.SRID = SRID;
     }
     toJson() {
-        return {
-            Type: this.Collection ? `Collection(${this.Type})` : this.Type,
-            Nullable: this.Nullable,
-            MaxLength: this.MaxLength,
-            Precision: this.Precision,
-            Scale: this.Scale,
-            SRID: this.SRID,
+        const json = {
+            Type: this.Collection ? `Collection(${this.Type})` : this.Type
         };
+        if (this.Nullable !== undefined) {
+            json['Nullable'] = this.Nullable;
+        }
+        if (this.MaxLength !== undefined) {
+            json['MaxLength'] = this.MaxLength;
+        }
+        if (this.Precision !== undefined) {
+            json['Precision'] = this.Precision;
+        }
+        if (this.Scale !== undefined) {
+            json['Scale'] = this.Scale;
+        }
+        if (this.SRID !== undefined) {
+            json['SRID'] = this.SRID;
+        }
+        return json;
     }
     toConfig() {
-        return {
+        const config = {
             type: this.Type,
-            collection: false,
+            collection: this.Collection
         };
+        if (this.Nullable !== undefined) {
+            config.nullable = this.Nullable;
+        }
+        if (this.MaxLength !== undefined) {
+            config.maxLength = this.MaxLength;
+        }
+        if (this.Precision !== undefined) {
+            config.precision = this.Precision;
+        }
+        if (this.Scale !== undefined) {
+            config.scale = this.Scale;
+        }
+        if (this.SRID !== undefined) {
+            config.srid = this.SRID;
+        }
+        return config;
     }
 }
 
@@ -9460,8 +9530,6 @@ class ODataMetadataParser {
             case ODataMetadataParser.ATTRIBUTE_TERM:
             case ODataMetadataParser.ATTRIBUTE_QUALIFIER:
             case ODataMetadataParser.ATTRIBUTE_STRING:
-            case ODataMetadataParser.ATTRIBUTE_BOOL:
-            case ODataMetadataParser.ATTRIBUTE_INT:
             case ODataMetadataParser.ATTRIBUTE_TARGET_NAMESPACE:
             case ODataMetadataParser.ATTRIBUTE_NAME:
             case ODataMetadataParser.ATTRIBUTE_TYPE:
@@ -9483,6 +9551,7 @@ class ODataMetadataParser {
             case ODataMetadataParser.ATTRIBUTE_BASE_TERM:
             case ODataMetadataParser.ATTRIBUTE_APPLIES_TO:
                 return this.getAttributeValue(attributes, field.name);
+            case ODataMetadataParser.ATTRIBUTE_BOOL:
             case ODataMetadataParser.ATTRIBUTE_NULLABLE:
             case ODataMetadataParser.ATTRIBUTE_UNICODE:
             case ODataMetadataParser.ATTRIBUTE_OPEN_TYPE:
@@ -9494,6 +9563,7 @@ class ODataMetadataParser {
             case ODataMetadataParser.ATTRIBUTE_ABSTRACT:
             case ODataMetadataParser.ATTRIBUTE_IS_FLAGS:
                 return this.propertyValueToBoolean(this.getAttributeValue(attributes, field.name));
+            case ODataMetadataParser.ATTRIBUTE_INT:
             case ODataMetadataParser.ATTRIBUTE_VALUE:
             case ODataMetadataParser.ATTRIBUTE_MAX_LENGTH:
             case ODataMetadataParser.ATTRIBUTE_PRECISION:
@@ -11348,7 +11418,7 @@ class ODataModel {
             resource instanceof ODataNavigationPropertyResource))
             return throwError(() => new Error('save: Resource type ODataEntityResource/ODataNavigationPropertyResource needed'));
         // Resolve method and resource key
-        if (method === undefined && this.schema().isCompoundKey())
+        if (method === undefined && this.isCompoundKey())
             return throwError(() => new Error('save: Composite key require a specific method, use create/update/modify'));
         method = method || (!resource.hasKey() ? 'create' : 'update');
         if (resource instanceof ODataEntityResource &&
@@ -11425,6 +11495,9 @@ class ODataModel {
     isNew() {
         return !this._meta.hasKey(this);
     }
+    isCompoundKey() {
+        return this.schema().isCompoundKey();
+    }
     withResource(resource, ctx) {
         return this._meta.withResource(this, resource, ctx);
     }
@@ -13019,7 +13092,7 @@ class ODataApi {
         });
         return true;
     }
-    populate({ schemas, references, models, collections }) {
+    populate({ schemas, references, models, collections, }) {
         const odataSchemas = (schemas ?? []).map((schema) => new ODataSchema(schema, this));
         //TODO: Merge duplicates
         this.schemas = [...this.schemas, ...odataSchemas];