breeze-client 2.2.2 → 3.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2012-2025 IdeaBlade
+Copyright (c) 2012-2026 IdeaBlade
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,63 +1,83 @@
-<p align="center"><a href="http://www.getbreezenow.com/" target="_blank"><img src="http://breeze.github.io/images/logos/BreezeJsB.png" alt="Breeze" width="100"/></a></p>
-
-# [Breeze](http://breeze.github.io/doc-main/) Data Management for JavaScript Clients  
-
-**Breeze** is a library that helps you manage data in rich client applications. If you store data in a database, query and save those data as complex object graphs, and share these graphs across multiple screens of your JavaScript client, Breeze is for you.
-
-Client-side querying, caching, dynamic object graphs, change tracking and notification, model validation, batch save, offline … all part of rich data management with Breeze.  Breeze clients communicate with any remote service that speaks HTTP and JSON.
-
-**Breeze** lets you develop applications using the same powerful idioms on the client and server. You can
-
-- query with a rich query syntax
-- navigate the graph of related entities
-- track changes as you add/change/delete entities
-- perform client-side validation
-- save all changes in a single transaction
-- use the same entity model on the server and client
-
-## Install from npm
-
-    npm install breeze-client
-or 
-
-    npm install breeze-client@cjs
-
-The version tagged `cjs` uses an older Angular Package Format, and includes ES5 and ES2015 versions, as well as UMD bundles.
-
-The version tagged `latest` (and `mjs`) uses updated [Angular Package Format](https://docs.google.com/document/d/1CZC2rcpxffTDfRDs6p1cfbmKNLA6x5O-NtkJglDaBVs/preview) and ES2022 .mjs modules.  It has `esm2022` and `fesm2022` folders, but no UMD `bundles` folder.
-
-If you want the latest module format, and don't care about UMD bundles, use `breeze-client`.
-
-If you need UMD bundles, or need backward compatibility with ES5 or ES2015, use `breeze-client@cjs`.
-
-## Documentation 
-
-See the [docs](http://breeze.github.io/doc-js/features.html) for more info about what Breeze does and how to use it.
-
-Set the [release notes](http://breeze.github.io/doc-js/release-notes.html) for changes in the latest version.
-
-## Examples
-
-See some [examples](https://github.com/Breeze/northwind-demo) of how to use breeze with Angular, Aurelia, React, and Vue in the [Northwind-Demo](https://github.com/Breeze/northwind-demo).
-
-See the [TempHire](https://github.com/Breeze/temphire.angular) application for a richer example showing proper architectural patterns.
-
-## Sources
-
-The sources for this package are in the [breeze-client](https://github.com/Breeze/breeze-client) repo.  Please file issues and pull requests against that repo.
-
-## Upgrading Breeze
-
-See the [UPGRADE](https://github.com/Breeze/breeze-client/blob/master/UPGRADE.md) document for information on upgrading from Breeze 1.x to 2.x.
-
-## Building Breeze
-
-See the [BUILD](https://github.com/Breeze/breeze-client/blob/master/BUILD.md) document for instructions on building the Breeze and its API docs.
-
-<hr>
-
-If you have discovered a bug or missing feature, please create an issue in the [breeze-client github repo](https://github.com/Breeze/breeze-client).
-
-If you have questions about using Breeze, please ask on [Stack Overflow](https://stackoverflow.com/questions/tagged/breeze).
-
-If you need help developing your application, please contact us at [IdeaBlade](mailto:info@ideablade.com).
+<p align="center"><a href="http://breeze.github.io/" target="_blank"><img src="http://breeze.github.io/images/logos/BreezeJsB.png" alt="Breeze" width="100"/></a></p>
+
+# Breeze Data Management for JavaScript Clients
+
+**Breeze** is a library from [IdeaBlade](https://www.ideablade.com/) that helps you manage
+data in rich client applications. If you store data in a database, query and save it as
+complex object graphs, and share those graphs across screens, Breeze is for you.
+
+Client-side querying, caching, dynamic object graphs, change tracking and notification,
+model validation, batch save, offline — all part of rich data management with Breeze.
+Breeze clients talk to any remote service that speaks HTTP and JSON.
+
+> **This is breeze-client 3**, published to npm as `breeze-client` 3.0.0.
+> 2.x is maintained in [breeze-client](https://github.com/Breeze/breeze-client).
+
+## What v3 is
+
+Same public API, rewritten for modern TypeScript, with a build you can read in one sitting.
+
+- **ESM only**, one package, one npm tag. No CommonJS, no UMD, no `mjs`/`cjs` dist-tags.
+- **One `tsc` invocation.** No ng-packagr, no second `node_modules`, no `downlevel-dts`.
+- **No runtime dependencies.**
+- **Knockout, jQuery, AngularJS and OData removed**, including CSDL/EDMX metadata parsing.
+- Angular support moves to its own package so Angular and RxJS stay out of the core build.
+
+Source is 42 files / 15,630 lines, down from 51 / 19,708.
+
+## Documentation
+
+| | |
+|---|---|
+| [UPGRADE.md](./UPGRADE.md) | **Converting an app from 2.x** — every consumer-facing change |
+| [TESTING.md](./TESTING.md) | **Running the tests** — creating the database, starting the server |
+| [DOCS.md](./DOCS.md) | **Building and viewing the docs** — the guides and the API reference |
+| [BUILD-AND-PACK.md](./BUILD-AND-PACK.md) | **Packing the library and trying it in another app** without publishing |
+| [CHANGES-DEV.md](./CHANGES-DEV.md) | Structural changes, for people working on Breeze itself |
+| [STATUS.md](./STATUS.md) | What is done, what is in flight, what is next |
+
+The user documentation is at [breeze.github.io/breeze-client-v3](https://breeze.github.io/breeze-client-v3/).
+The 2.x documentation is still at [breeze.github.io/doc-js](https://breeze.github.io/doc-js/?v2).
+
+## Install
+
+```bash
+npm install breeze-client
+```
+
+```ts
+import { EntityManager, EntityQuery } from 'breeze-client';
+
+const em = new EntityManager('/breeze/Northwind');
+const { results } = await em.executeQuery(EntityQuery.from('Customers').take(10));
+```
+
+That is all a Breeze .NET server needs. There are no adapters to import or register, and
+property names are camel-cased by default: `CompanyName` on the server is `companyName`
+on the client. If your server already sends the names the client should use, call
+`NamingConvention.none.setAsDefault()` at startup, before creating an `EntityManager`.
+2.x defaulted to `none` — see [UPGRADE.md](./UPGRADE.md).
+
+## Building
+
+```bash
+npm install
+npm run typecheck     # tsc --noEmit
+npm run build         # -> dist/
+```
+
+## Server
+
+The .NET server lives in
+[breeze-server-v3](https://github.com/Breeze/breeze-server-v3). The integration tests in
+this repo run against it.
+
+---
+
+If you have discovered a bug or missing feature, please create an issue.
+
+If you have questions about using Breeze, please ask on
+[Stack Overflow](https://stackoverflow.com/questions/tagged/breeze).
+
+If you need help developing your application, please contact us at
+[IdeaBlade](mailto:info@ideablade.com).

package/adapters/abstract-data-service-adapter.d.ts

@@ -0,0 +1,120 @@
+import { DataServiceAdapter, AjaxAdapter, AjaxConfig, ChangeRequestInterceptorCtor, ChangeRequestInterceptor } from '../config/interface-registry.js';
+import { MappingContext } from '../query/mapping-context.js';
+import { DataService, JsonResultsAdapter } from '../metadata/data-service.js';
+import { HttpResponse, SaveContext, SaveBundle, ServerError, SaveResult, QueryResult } from '../manager/entity-manager.js';
+import { MetadataStore } from '../metadata/entity-metadata.js';
+/** For use by breeze plugin authors only.  The class is used as the base class for most {@link DataServiceAdapter} implementations
+@adapter (see {@link DataServiceAdapter})
+@hidden
+*/
+export declare abstract class AbstractDataServiceAdapter implements DataServiceAdapter {
+    /** The name of this adapter. */
+    name: string;
+    /**
+     * The ajax adapter requests go through: the registered default if there is one, otherwise
+     * a built-in one that uses `config.fetch`.
+     * @deprecated Make requests with `_ajax`, and supply the transport with
+     * `configureBreeze({ fetch })`.
+     */
+    ajaxImpl: AjaxAdapter;
+    checkForRecomposition(interfaceInitializedArgs: any): void;
+    initialize(): void;
+    /**
+     * Sends one request. Resolves with the response, or rejects with a `ServerError`.
+     *
+     * Subclasses should make their requests through this method rather than through
+     * `ajaxImpl`, whose callback-shaped contract is kept only for compatibility. This is the
+     * only place in the class that deals in success/error callbacks.
+     */
+    protected _ajax(config: Omit<AjaxConfig, 'success' | 'error'>, errorMessagePrefix?: string, prepareResponse?: (httpResponse: HttpResponse) => void): Promise<HttpResponse>;
+    fetchMetadata(metadataStore: MetadataStore, dataService: DataService): Promise<any>;
+    /** Execute the query in the mappingContext. */
+    executeQuery(mappingContext: MappingContext): Promise<QueryResult>;
+    /** Set up ajax parameters for query GET.  This puts the query into the request querystring, in whatever syntax the UriBuilder produces. */
+    _makeQueryGetParams(mappingContext: MappingContext): {
+        type: string;
+        url: string;
+        params: Object;
+        dataType: string;
+        crossDomain: boolean;
+    };
+    /** Set up ajax parameters for query POST.  This put the query into the request body as JSON. */
+    _makeQueryPostParams(mappingContext: MappingContext): {
+        type: string;
+        url: string;
+        params: Object;
+        dataType: string;
+        processData: boolean;
+        contentType: string;
+        data: string;
+        crossDomain: boolean;
+    };
+    saveChanges(saveContext: SaveContext, saveBundle: SaveBundle): Promise<SaveResult>;
+    /** Abstract method that needs to be overwritten in any concrete DataServiceAdapter subclass.
+    The return value from this method should be a serializable object that will be sent to the server after calling JSON.stringify on it.
+    */
+    _prepareSaveBundle(saveContext: SaveContext, saveBundle: SaveBundle): any;
+    /**
+    Returns a constructor function for a "ChangeRequestInterceptor"
+    that can tweak the saveBundle both as it is built and when it is completed
+    by a concrete DataServiceAdapater.
+  
+    Initialized with a default, no-op implementation that developers can replace with a
+    substantive implementation that changes the individual entity change requests
+    or aspects of the entire 'saveBundle' without having to write their own DataService adapters.
+    ```ts
+    let adapter = breeze.config.getAdapterInstance('dataService');
+    adapter.changeRequestInterceptor = function (saveContext, saveBundle) {
+        this.getRequest = function (request, entity, index) {
+           // alter the request that the adapter prepared for this entity
+           // based on the entity, saveContext, and saveBundle
+           // e.g., add a custom header or prune the originalValuesMap
+           return request;
+       };
+       this.done = function (requests) {
+           // alter the array of requests representing the entire change-set
+           // based on the saveContext and saveBundle
+       };
+    }
+    ```
+  
+    @param saveContext - The BreezeJS "context" for the save operation.
+    @param saveBundle - Contains the array of entities-to-be-saved (AKA, the entity change-set).
+    @returns Constructor for a "ChangeRequestInterceptor".
+    */
+    changeRequestInterceptor: ChangeRequestInterceptorCtor;
+    /**
+     * Creates the change request interceptor for one save, from `changeRequestInterceptor`.
+     * Call it at the start of `_prepareSaveBundle`, pass each entity's request through its
+     * `getRequest`, and pass the finished array to its `done`.
+     *
+     * Falls back to a no-op interceptor when `changeRequestInterceptor` is not set. If the
+     * interceptor it creates has `oneTime` set, the adapter goes back to the no-op
+     * interceptor afterwards, so only this save is intercepted.
+     * @throws if the interceptor has no `getRequest` or `done` method.
+     */
+    protected _createChangeRequestInterceptor(saveContext: SaveContext, saveBundle: SaveBundle): ChangeRequestInterceptor;
+    /** Abstract method that needs to be overwritten in any concrete DataServiceAdapter sublclass.
+    This method needs to take the result returned the server and convert it into an ISaveResult.
+    */
+    _prepareSaveResult(saveContext: SaveContext, data: any): SaveResult;
+    /** Utility method that may be used in any concrete DataServiceAdapter sublclass to handle any
+    http connection issues. For an error with status 0 - the request got no response - it says in
+    the message that the server could not be reached, keeping any message the transport gave.
+    An aborted request is left alone. `makeHttpError` already applies it.
+    */
+    static _catchNoConnectionError(err: ServerError): void;
+    /**
+     * Builds the Breeze error for a failed HTTP response: an `Error` carrying `status`,
+     * `statusText`, `url`, `body` and `httpResponse`, whose message comes from the response
+     * body (a .NET exception, or `{ message, errors }`). For a save, it also carries the
+     * server's per-entity `entityErrors`, if `httpResponse.saveContext` is set.
+     *
+     * `_ajax` uses it for every failed request. Call it when your adapter makes a request some
+     * other way, then throw or reject with the result.
+     * @param httpResponse - The failed response.
+     * @param messagePrefix - Put at the start of the message, followed by "; ".
+     */
+    static makeHttpError(httpResponse: HttpResponse, messagePrefix?: string): ServerError;
+    jsonResultsAdapter: JsonResultsAdapter;
+}