@statezero/core 0.2.38 → 0.2.40

package/dist/flavours/django/manager.d.ts

@@ -0,0 +1,204 @@
+/**
+ * @typedef {Object} SerializerOptions
+ * @property {number} [depth] - How deep to serialize nested objects.
+ * @property {string[]} [fields] - List of fields to include.
+ * @property {number} [limit] - Maximum number of items to retrieve.
+ * @property {number} [offset] - Offset for pagination.
+ * @property {number} [overfetch] - Overfetch additional items.
+ * @property {string} [namespace] - Custom namespace for real-time updates.
+ */
+/**
+ * Manager class providing helper methods to work with QuerySets and models.
+ *
+ * @class Manager
+ */
+export class Manager {
+    /**
+     * Creates a new Manager.
+     *
+     * @param {Function} ModelClass - The model's constructor.
+     * @param {Function} [QuerySetClass=QuerySet] - The QuerySet class to use.
+     */
+    constructor(ModelClass: Function, QuerySetClass?: Function);
+    ModelClass: Function;
+    QuerySetClass: Function;
+    /**
+     * Creates a new QuerySet instance.
+     *
+     * @returns {QuerySet} A new QuerySet instance for the model.
+     */
+    newQuerySet(): QuerySet<any>;
+    /**
+     * Retrieves a single model instance matching the provided filters.
+     *
+     * @param {Object} [filters] - The filters to apply.
+     * @param {SerializerOptions} [serializerOptions] - Options for serialization.
+     * @returns {Promise<Model>} A promise that resolves to the model instance.
+     */
+    get(filters?: Object, serializerOptions?: SerializerOptions): Promise<Model>;
+    /**
+     * Filters the QuerySet based on the provided conditions.
+     *
+     * @param {*} conditions - The filter conditions.
+     * @returns {QuerySet} A new QuerySet instance with the filters applied.
+     */
+    filter(conditions: any): QuerySet<any>;
+    /**
+     * Excludes the specified conditions from the QuerySet.
+     *
+     * @param {*} conditions - The conditions to exclude.
+     * @returns {QuerySet} A new QuerySet instance with the conditions excluded.
+     */
+    exclude(conditions: any): QuerySet<any>;
+    /**
+     * Returns a QuerySet representing all records.
+     *
+     * @returns {QuerySet} A new QuerySet instance.
+     */
+    all(): QuerySet<any>;
+    /**
+     * Returns a QuerySet that executes remotely without updating local stores.
+     *
+     * @returns {QuerySet} A remote-only QuerySet instance.
+     */
+    remote(): QuerySet<any>;
+    /**
+     * Deletes records in the QuerySet.
+     *
+     * @returns {Promise<[number, Object]>} A promise that resolves to an array where the first element is
+     * the number of records deleted and the second is an object with details.
+     */
+    delete(): Promise<[number, Object]>;
+    /**
+     * Counts the number of records matching the current query.
+     *
+     * @param {string} [field] - Optional field to count (defaults to 'pk')
+     * @returns {Promise<number>} A promise that resolves to the count
+     */
+    count(field?: string): Promise<number>;
+    /**
+     * Computes the sum of values for the specified field.
+     *
+     * @param {string} field - The field to sum
+     * @returns {Promise<number>} A promise that resolves to the sum
+     */
+    sum(field: string): Promise<number>;
+    /**
+     * Computes the average value for the specified field.
+     *
+     * @param {string} field - The field to average
+     * @returns {Promise<number>} A promise that resolves to the average
+     */
+    avg(field: string): Promise<number>;
+    /**
+     * Finds the minimum value for the specified field.
+     *
+     * @param {string} field - The field to find the minimum value for
+     * @returns {Promise<any>} A promise that resolves to the minimum value
+     */
+    min(field: string): Promise<any>;
+    /**
+     * Finds the maximum value for the specified field.
+     *
+     * @param {string} field - The field to find the maximum value for
+     * @returns {Promise<any>} A promise that resolves to the maximum value
+     */
+    max(field: string): Promise<any>;
+    /**
+     * Checks if any records exist that match the current query.
+     *
+     * @returns {Promise<boolean>} A promise that resolves to true if records exist, otherwise false
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Orders the QuerySet by the provided fields.
+     *
+     * @param {...(string|any)} fields - The fields to order by. Supports nested paths and descending order
+     * (prefix field with '-').
+     * @returns {QuerySet} A new QuerySet instance with the order applied.
+     */
+    orderBy(...fields: (string | any)[]): QuerySet<any>;
+    /**
+     * Creates a new model instance using the provided data, then saves it.
+     *
+     * @param {*} data - The data to create the model instance.
+     * @returns {Promise<*>} A promise that resolves to the newly created model instance.
+     */
+    create(data: any): Promise<any>;
+    /**
+     * Creates multiple model instances using the provided model instances.
+     *
+     * @param {Array<Model>} modelInstances - Array of unsaved model instances to create.
+     * @returns {Promise<Array<*>>} A promise that resolves to an array of newly created model instances.
+     */
+    bulkCreate(modelInstances: Array<Model>): Promise<Array<any>>;
+    /**
+     * Fetches all records using the current QuerySet.
+     *
+     * @param {SerializerOptions} [serializerOptions] - Options for serialization.
+     * @returns {Promise<Array<*>>} A promise that resolves to an array of model instances.
+     */
+    fetch(serializerOptions?: SerializerOptions): Promise<Array<any>>;
+    /**
+     * Retrieves or creates a model instance based on lookup fields and defaults.
+     *
+     * @param {*} lookupFields - The fields to lookup the model.
+     * @param {Object} [defaults={}] - Default values to use when creating a new instance.
+     * @returns {Promise<ResultTuple>} A promise that resolves to a ResultTuple containing the model instance
+     * and a boolean indicating whether it was created.
+     */
+    getOrCreate(lookupFields: any, defaults?: Object): Promise<ResultTuple>;
+    /**
+     * Updates or creates a model instance based on lookup fields and defaults.
+     *
+     * @param {*} lookupFields - The fields to lookup the model.
+     * @param {Object} [defaults={}] - Default values to use when updating or creating the instance.
+     * @returns {Promise<ResultTuple>} A promise that resolves to a ResultTuple containing the model instance
+     * and a boolean indicating whether it was created.
+     */
+    updateOrCreate(lookupFields: any, defaults?: Object): Promise<ResultTuple>;
+    /**
+     * Applies a search to the QuerySet using the specified search query and fields.
+     *
+     * @param {string} searchQuery - The search query.
+     * @param {string[]} [searchFields] - The fields to search in.
+     * @returns {QuerySet} A new QuerySet instance with the search applied.
+     */
+    search(searchQuery: string, searchFields?: string[]): QuerySet<any>;
+    /**
+     * Returns a QuerySet marked as optimistic-only, meaning operations will only
+     * update local state without making backend API calls.
+     *
+     * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
+     */
+    get optimistic(): QuerySet<any>;
+}
+export type SerializerOptions = {
+    /**
+     * - How deep to serialize nested objects.
+     */
+    depth?: number | undefined;
+    /**
+     * - List of fields to include.
+     */
+    fields?: string[] | undefined;
+    /**
+     * - Maximum number of items to retrieve.
+     */
+    limit?: number | undefined;
+    /**
+     * - Offset for pagination.
+     */
+    offset?: number | undefined;
+    /**
+     * - Overfetch additional items.
+     */
+    overfetch?: number | undefined;
+    /**
+     * - Custom namespace for real-time updates.
+     */
+    namespace?: string | undefined;
+};
+import { QuerySet } from './querySet.js';
+import { Model } from './model.js';
+import { ResultTuple } from './queryExecutor.js';

package/dist/flavours/django/manager.js

@@ -0,0 +1,222 @@
+import { QuerySet } from './querySet.js';
+import { Model } from './model.js';
+import { QueryExecutor, ResultTuple } from './queryExecutor.js';
+import axios from 'axios';
+/**
+ * @typedef {Object} SerializerOptions
+ * @property {number} [depth] - How deep to serialize nested objects.
+ * @property {string[]} [fields] - List of fields to include.
+ * @property {number} [limit] - Maximum number of items to retrieve.
+ * @property {number} [offset] - Offset for pagination.
+ * @property {number} [overfetch] - Overfetch additional items.
+ * @property {string} [namespace] - Custom namespace for real-time updates.
+ */
+/**
+ * Manager class providing helper methods to work with QuerySets and models.
+ *
+ * @class Manager
+ */
+export class Manager {
+    /**
+     * Creates a new Manager.
+     *
+     * @param {Function} ModelClass - The model's constructor.
+     * @param {Function} [QuerySetClass=QuerySet] - The QuerySet class to use.
+     */
+    constructor(ModelClass, QuerySetClass = QuerySet) {
+        this.ModelClass = ModelClass;
+        this.QuerySetClass = QuerySetClass;
+    }
+    /**
+     * Creates a new QuerySet instance.
+     *
+     * @returns {QuerySet} A new QuerySet instance for the model.
+     */
+    newQuerySet() {
+        return new this.QuerySetClass(this.ModelClass);
+    }
+    /**
+     * Retrieves a single model instance matching the provided filters.
+     *
+     * @param {Object} [filters] - The filters to apply.
+     * @param {SerializerOptions} [serializerOptions] - Options for serialization.
+     * @returns {Promise<Model>} A promise that resolves to the model instance.
+     */
+    async get(filters, serializerOptions) {
+        return this.newQuerySet().get(filters, serializerOptions);
+    }
+    /**
+     * Filters the QuerySet based on the provided conditions.
+     *
+     * @param {*} conditions - The filter conditions.
+     * @returns {QuerySet} A new QuerySet instance with the filters applied.
+     */
+    filter(conditions) {
+        return this.newQuerySet().filter(conditions);
+    }
+    /**
+     * Excludes the specified conditions from the QuerySet.
+     *
+     * @param {*} conditions - The conditions to exclude.
+     * @returns {QuerySet} A new QuerySet instance with the conditions excluded.
+     */
+    exclude(conditions) {
+        return this.newQuerySet().exclude(conditions);
+    }
+    /**
+     * Returns a QuerySet representing all records.
+     *
+     * @returns {QuerySet} A new QuerySet instance.
+     */
+    all() {
+        return this.newQuerySet();
+    }
+    /**
+     * Returns a QuerySet that executes remotely without updating local stores.
+     *
+     * @returns {QuerySet} A remote-only QuerySet instance.
+     */
+    remote() {
+        return this.newQuerySet().remote();
+    }
+    /**
+     * Deletes records in the QuerySet.
+     *
+     * @returns {Promise<[number, Object]>} A promise that resolves to an array where the first element is
+     * the number of records deleted and the second is an object with details.
+     */
+    async delete() {
+        return await QueryExecutor.execute(this.newQuerySet(), 'delete');
+    }
+    /**
+     * Counts the number of records matching the current query.
+     *
+     * @param {string} [field] - Optional field to count (defaults to 'pk')
+     * @returns {Promise<number>} A promise that resolves to the count
+     */
+    async count(field) {
+        return await QueryExecutor.execute(this.newQuerySet(), 'count', { field });
+    }
+    /**
+     * Computes the sum of values for the specified field.
+     *
+     * @param {string} field - The field to sum
+     * @returns {Promise<number>} A promise that resolves to the sum
+     */
+    async sum(field) {
+        return await QueryExecutor.execute(this.newQuerySet(), 'sum', { field });
+    }
+    /**
+     * Computes the average value for the specified field.
+     *
+     * @param {string} field - The field to average
+     * @returns {Promise<number>} A promise that resolves to the average
+     */
+    async avg(field) {
+        return await QueryExecutor.execute(this.newQuerySet(), 'avg', { field });
+    }
+    /**
+     * Finds the minimum value for the specified field.
+     *
+     * @param {string} field - The field to find the minimum value for
+     * @returns {Promise<any>} A promise that resolves to the minimum value
+     */
+    async min(field) {
+        return await QueryExecutor.execute(this.newQuerySet(), 'min', { field });
+    }
+    /**
+     * Finds the maximum value for the specified field.
+     *
+     * @param {string} field - The field to find the maximum value for
+     * @returns {Promise<any>} A promise that resolves to the maximum value
+     */
+    async max(field) {
+        return await QueryExecutor.execute(this.newQuerySet(), 'max', { field });
+    }
+    /**
+     * Checks if any records exist that match the current query.
+     *
+     * @returns {Promise<boolean>} A promise that resolves to true if records exist, otherwise false
+     */
+    async exists() {
+        return await QueryExecutor.execute(this.newQuerySet(), 'exists');
+    }
+    /**
+     * Orders the QuerySet by the provided fields.
+     *
+     * @param {...(string|any)} fields - The fields to order by. Supports nested paths and descending order
+     * (prefix field with '-').
+     * @returns {QuerySet} A new QuerySet instance with the order applied.
+     */
+    orderBy(...fields) {
+        return this.newQuerySet().orderBy(...fields);
+    }
+    /**
+     * Creates a new model instance using the provided data, then saves it.
+     *
+     * @param {*} data - The data to create the model instance.
+     * @returns {Promise<*>} A promise that resolves to the newly created model instance.
+     */
+    async create(data) {
+        return this.newQuerySet().create(data);
+    }
+    /**
+     * Creates multiple model instances using the provided model instances.
+     *
+     * @param {Array<Model>} modelInstances - Array of unsaved model instances to create.
+     * @returns {Promise<Array<*>>} A promise that resolves to an array of newly created model instances.
+     */
+    async bulkCreate(modelInstances) {
+        return this.newQuerySet().bulkCreate(modelInstances);
+    }
+    /**
+     * Fetches all records using the current QuerySet.
+     *
+     * @param {SerializerOptions} [serializerOptions] - Options for serialization.
+     * @returns {Promise<Array<*>>} A promise that resolves to an array of model instances.
+     */
+    async fetch(serializerOptions) {
+        return this.newQuerySet().fetch(serializerOptions);
+    }
+    /**
+     * Retrieves or creates a model instance based on lookup fields and defaults.
+     *
+     * @param {*} lookupFields - The fields to lookup the model.
+     * @param {Object} [defaults={}] - Default values to use when creating a new instance.
+     * @returns {Promise<ResultTuple>} A promise that resolves to a ResultTuple containing the model instance
+     * and a boolean indicating whether it was created.
+     */
+    async getOrCreate(lookupFields, defaults = {}) {
+        return this.newQuerySet().getOrCreate(lookupFields, defaults);
+    }
+    /**
+     * Updates or creates a model instance based on lookup fields and defaults.
+     *
+     * @param {*} lookupFields - The fields to lookup the model.
+     * @param {Object} [defaults={}] - Default values to use when updating or creating the instance.
+     * @returns {Promise<ResultTuple>} A promise that resolves to a ResultTuple containing the model instance
+     * and a boolean indicating whether it was created.
+     */
+    async updateOrCreate(lookupFields, defaults = {}) {
+        return this.newQuerySet().updateOrCreate(lookupFields, defaults);
+    }
+    /**
+     * Applies a search to the QuerySet using the specified search query and fields.
+     *
+     * @param {string} searchQuery - The search query.
+     * @param {string[]} [searchFields] - The fields to search in.
+     * @returns {QuerySet} A new QuerySet instance with the search applied.
+     */
+    search(searchQuery, searchFields) {
+        return this.newQuerySet().search(searchQuery, searchFields);
+    }
+    /**
+     * Returns a QuerySet marked as optimistic-only, meaning operations will only
+     * update local state without making backend API calls.
+     *
+     * @returns {QuerySet} A new QuerySet with optimistic-only mode enabled.
+     */
+    get optimistic() {
+        return this.newQuerySet()._optimistic();
+    }
+}

package/dist/flavours/django/model.d.ts

@@ -0,0 +1,137 @@
+/**
+ * A constructor for a Model.
+ *
+ * @typedef {Function} ModelConstructor
+ * @param {any} data - Data to initialize the model.
+ * @returns {Model}
+ *
+ * @property {Manager} objects - The model's manager.
+ * @property {string} configKey - The configuration key.
+ * @property {string} modelName - The model name.
+ * @property {string} primaryKeyField - The primary key field (default 'id').
+ */
+/**
+ * Base Model class with integrated API implementation.
+ *
+ * @abstract
+ */
+export class Model {
+    /**
+     * Creates a new Model instance.
+     *
+     * @param {any} [data={}] - The data for initialization.
+     */
+    static instanceCache: Map<any, any>;
+    /**
+     * Remote-only manager that skips local store updates.
+     */
+    static get remote(): any;
+    /**
+     * Instantiate from pk using queryset scoped singletons
+     */
+    static fromPk(pk: any, querySet: any): any;
+    /**
+     * Validates that the provided data object only contains keys
+     * defined in the model's allowed fields. Supports nested fields
+     * using double underscore notation (e.g., author__name).
+     *
+     * @param {Object} data - The object to validate.
+     * @throws {ValidationError} If an unknown key is found.
+     */
+    static validateFields(data: Object): void;
+    /**
+     * Static method to validate data without creating an instance
+     * @param {Object} data - Data to validate
+     * @param {string} validateType - 'create' or 'update'
+     * @param {boolean} partial - Whether to allow partial validation
+     * @returns {Promise<boolean>} Promise that resolves to true if valid, throws error if invalid
+     */
+    static validate(data: Object, validateType?: string, partial?: boolean): Promise<boolean>;
+    /**
+     * Get field permissions for the current user (cached on the class)
+     * @param {boolean} refresh - Force refresh the cached permissions
+     * @returns {Promise<{visible_fields: string[], creatable_fields: string[], editable_fields: string[]}>}
+     */
+    static getFieldPermissions(refresh?: boolean): Promise<{
+        visible_fields: string[];
+        creatable_fields: string[];
+        editable_fields: string[];
+    }>;
+    constructor(data?: {});
+    serializer: ModelSerializer;
+    _data: {};
+    _pk: any;
+    __version: number;
+    touch(): void;
+    /**
+     * Sets the primary key of the model instance.
+     *
+     * @param {number|undefined} value - The new primary key value.
+     */
+    set pk(value: number | undefined);
+    /**
+     * Returns the primary key of the model instance.
+     *
+     * @returns {number|undefined} The primary key.
+     */
+    get pk(): number | undefined;
+    /**
+     * Gets a field value from the internal data store
+     *
+     * @param {string} field - The field name
+     * @returns {any} The field value
+     */
+    getField(field: string): any;
+    /**
+     * Sets a field value in the internal data store
+     *
+     * @param {string} field - The field name
+     * @param {any} value - The field value to set
+     */
+    setField(field: string, value: any): void;
+    /**
+     * Serializes the model instance.
+     *
+     * By default, it returns all enumerable own properties.
+     * Subclasses should override this to return specific keys.
+     *
+     * @param {boolean} includeRepr - Whether to include the repr field (for caching). Default: false.
+     * @returns {Object} The serialized model data.
+     */
+    serialize(includeRepr?: boolean): Object;
+    /**
+     * Saves the model instance by either creating a new record or updating an existing one.
+     *
+     * @returns {Promise<Model>} A promise that resolves to the updated model instance.
+     */
+    save(): Promise<Model>;
+    /**
+     * Deletes the instance from the database.
+     *
+     * Returns a tuple with the number of objects deleted and an object mapping
+     * model names to the number of objects deleted, matching Django's behavior.
+     *
+     * @returns {Promise<[number, Object]>} A promise that resolves to the deletion result.
+     * @throws {Error} If the instance has not been saved (no primary key).
+     */
+    delete(): Promise<[number, Object]>;
+    /**
+     * Refreshes the model instance with data from the database.
+     *
+     * @returns {Promise<void>} A promise that resolves when the instance has been refreshed.
+     * @throws {Error} If the instance has not been saved (no primary key).
+     */
+    refreshFromDb(): Promise<void>;
+    /**
+     * Validates the model instance using the same serialize behavior as save()
+     * @param {string} validateType - 'create' or 'update' (defaults to auto-detect)
+     * @param {boolean} partial - Whether to allow partial validation
+     * @returns {Promise<boolean>} Promise that resolves to true if valid, throws error if invalid
+     */
+    validate(validateType?: string, partial?: boolean): Promise<boolean>;
+}
+/**
+ * A constructor for a Model.
+ */
+export type ModelConstructor = Function;
+import { ModelSerializer } from "./serializers.js";