@connecttomahdi/rxdb 17.0.0-beta.17 → 17.1.1

package/scripts/check-code-block-line-length.js

@@ -0,0 +1,91 @@
+const fs = require('fs');
+const path = require('path');
+
+const MAX_LINE_LENGTH = 86;
+
+const targetDirs = [
+    path.join(__dirname, '../docs-src/docs'),
+    path.join(__dirname, '../docs-src/src')
+];
+
+let hasError = false;
+
+function walkDir(dir) {
+    if (!fs.existsSync(dir)) return;
+    const files = fs.readdirSync(dir);
+    for (const file of files) {
+        const fullPath = path.join(dir, file);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+            walkDir(fullPath);
+        } else if (
+            fullPath.endsWith('.md') ||
+            fullPath.endsWith('.mdx')
+        ) {
+            checkFile(fullPath);
+        }
+    }
+}
+
+function checkFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    let inCodeBlock = false;
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+
+        if (trimmed.startsWith('```')) {
+            // Single-line code block: ```code```
+            const rest = trimmed.slice(3);
+            if (rest.endsWith('```') && rest.length > 3) {
+                continue;
+            }
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+
+        if (inCodeBlock && line.length > MAX_LINE_LENGTH) {
+            const relativePath = path.relative(
+                path.join(__dirname, '..'),
+                filePath
+            );
+            console.error(
+                'Error: Code block line too long ' +
+                `(${line.length} > ${MAX_LINE_LENGTH}) ` +
+                `in ${relativePath}:${i + 1}`
+            );
+            console.error(`> ${line}`);
+            console.error('-'.repeat(100));
+            hasError = true;
+        }
+    }
+}
+
+console.log(
+    'Checking documentation code blocks ' +
+    `for lines longer than ${MAX_LINE_LENGTH} characters...`
+);
+
+for (const dir of targetDirs) {
+    walkDir(dir);
+}
+
+if (hasError) {
+    console.error(
+        '\nDocumentation contains code block lines ' +
+        `exceeding ${MAX_LINE_LENGTH} characters.`
+    );
+    console.error(
+        'Please shorten these lines to fit within the limit.'
+    );
+    process.exit(1);
+} else {
+    console.log(
+        'Success: All code block lines are within ' +
+        `${MAX_LINE_LENGTH} characters.`
+    );
+    process.exit(0);
+}

package/scripts/check-em-dashes.js

@@ -0,0 +1,53 @@
+const fs = require('fs');
+const path = require('path');
+
+const targetDirs = [
+    path.join(__dirname, '../docs-src/docs'),
+    path.join(__dirname, '../docs-src/src')
+];
+
+let hasError = false;
+
+function walkDir(dir) {
+    if (!fs.existsSync(dir)) return;
+    const files = fs.readdirSync(dir);
+    for (const file of files) {
+        const fullPath = path.join(dir, file);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+            walkDir(fullPath);
+        } else if (fullPath.endsWith('.md') || fullPath.endsWith('.mdx') || fullPath.endsWith('.tsx') || fullPath.endsWith('.ts')) {
+            checkFile(fullPath);
+        }
+    }
+}
+
+function checkFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.includes('—') || line.includes('–')) {
+            console.error(`Error: Em/En dash found in ${filePath}:${i + 1}`);
+            console.error(`> ${line.trim()}`);
+            console.error('-'.repeat(100));
+            hasError = true;
+        }
+    }
+}
+
+console.log('Checking documentation for em-dashes and en-dashes...');
+
+for (const dir of targetDirs) {
+    walkDir(dir);
+}
+
+if (hasError) {
+    console.error('\nDocumentation contains prohibited em-dash (—) or en-dash (–) characters.');
+    console.error('Please rephrase to comply with project guidelines.');
+    process.exit(1);
+} else {
+    console.log('Success: No em-dashes or en-dashes found.');
+    process.exit(0);
+}

package/scripts/copy-path.mjs

@@ -0,0 +1,20 @@
+import { promises as fs } from 'node:fs';
+
+async function main() {
+    const [, , sourcePath, targetPath] = process.argv;
+
+    if (!sourcePath || !targetPath) {
+        console.error('copy-path requires <source> and <target>');
+        process.exit(1);
+    }
+
+    await fs.cp(sourcePath, targetPath, {
+        recursive: true,
+        force: true
+    });
+}
+
+main().catch(err => {
+    console.error(`copy-path error: ${err.message}`);
+    process.exit(1);
+});

package/scripts/docs-fetch-git-history.mjs

@@ -0,0 +1,36 @@
+/**
+ * Docusaurus uses 'git log' to determine the last update time for each docs page.
+ * In shallow clones (common in CI), all files report the same commit date
+ * because git only has one commit available. This causes every page to show
+ * the same "Last updated" date.
+ *
+ * This script ensures the full git history is available before building docs,
+ * so that 'git log' returns the actual per-file last modification date.
+ */
+import { execSync } from 'child_process';
+
+function run() {
+    let isShallow;
+    try {
+        isShallow = execSync('git rev-parse --is-shallow-repository', { encoding: 'utf-8' }).trim();
+    } catch (err) {
+        console.log('Could not determine if repository is shallow: ' + err.message);
+        console.log('Skipping git history fetch.');
+        return;
+    }
+
+    if (isShallow === 'true') {
+        console.log('Shallow repository detected. Fetching full git history for accurate docs timestamps...');
+        try {
+            execSync('git fetch --unshallow', { stdio: 'inherit' });
+            console.log('Full git history fetched successfully.');
+        } catch (err) {
+            console.warn('Warning: Could not fetch full git history: ' + err.message);
+            console.warn('Docs "Last updated" dates may be inaccurate.');
+        }
+    } else {
+        console.log('Full git history already available.');
+    }
+}
+
+run();

package/scripts/fix-types.mjs

@@ -1,11 +1,18 @@
-import { promises as fs } from 'node:fs';
-
-async function main () {
-    const file = './dist/types/index.d.ts';
-    try {
-        let content = await fs.readFile(file, { encoding: 'utf-8' });
-        // Convert only bare '.ts' specifier endings, keep existing '.d.ts' intact.
-        content = content.replace(/(?<!\.d)\.ts(?=['"])/g, '.d.ts');
+import { promises as fs } from 'node:fs';
+
+async function main () {
+    const sourceTypesDir = './src/types';
+    const targetTypesDir = './dist/types/types';
+    const file = './dist/types/index.d.ts';
+    try {
+        await fs.cp(sourceTypesDir, targetTypesDir, {
+            recursive: true,
+            force: true
+        });
+
+        let content = await fs.readFile(file, { encoding: 'utf-8' });
+        // Convert only bare '.ts' specifier endings, keep existing '.d.ts' intact.
+        content = content.replace(/(?<!\.d)\.ts(?=['"])/g, '.d.ts');
 
         // Guard against malformed declaration specifiers.
         if (/\.d\.d\.ts(?=['"])/.test(content)) {

package/scripts/install-foundationdb.sh

@@ -6,9 +6,3 @@ wget -O foundationdb-client.deb https://github.com/apple/foundationdb/releases/d
 sudo dpkg -i foundationdb-client.deb
 rm foundationdb-client.deb
 
-
-echo "# installing FoundationDB server:"
-wget -O foundationdb-server.deb https://github.com/apple/foundationdb/releases/download/7.3.59/foundationdb-server_7.3.59-1_amd64.deb
-sudo dpkg -i foundationdb-server.deb
-rm foundationdb-server.deb
-

package/scripts/notify-indexnow.mjs

@@ -0,0 +1,171 @@
+/**
+ * Notifies Bing IndexNow about changed documentation pages.
+ * Gathers all docs pages from docs-src/ and submits their URLs
+ * to the IndexNow API so that Bing re-indexes them.
+ *
+ * @link https://www.bing.com/indexnow/getstarted
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const INDEXNOW_KEY = 'bc55ad38ac6d4cdfa33c3f7f8667999b';
+const SITE_HOST = 'rxdb.info';
+const SITE_URL = 'https://' + SITE_HOST;
+const KEY_LOCATION = SITE_URL + '/' + INDEXNOW_KEY + '.txt';
+const INDEXNOW_ENDPOINT = 'https://api.indexnow.org/indexnow';
+
+const DOCS_DIR = path.join(__dirname, '..', 'docs-src', 'docs');
+const PAGES_DIR = path.join(__dirname, '..', 'docs-src', 'src', 'pages');
+
+const MAX_RETRIES = 5;
+
+/**
+ * Recursively walks a directory and calls the callback for each file.
+ */
+function walk(dir, callback) {
+    const list = fs.readdirSync(dir);
+    for (const file of list) {
+        const filePath = path.join(dir, file);
+        const stat = fs.statSync(filePath);
+        if (stat.isDirectory()) {
+            walk(filePath, callback);
+        } else {
+            callback(filePath);
+        }
+    }
+}
+
+/**
+ * Extracts the slug from markdown frontmatter.
+ * Falls back to the filename without extension.
+ */
+function getSlugFromMarkdown(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const frontMatch = content.match(/^---\s*([\s\S]*?)\s*---/);
+    if (!frontMatch) {
+        return path.basename(filePath, '.md');
+    }
+    const frontmatter = frontMatch[1];
+    const slugMatch = frontmatter.match(/slug:\s*(.*)/);
+    if (slugMatch) {
+        let slug = slugMatch[1].trim();
+        slug = slug.replace(/\.html$/, '');
+        return slug;
+    }
+    return path.basename(filePath, '.md');
+}
+
+/**
+ * Gathers all documentation page URLs from docs-src.
+ */
+function gatherPageUrls() {
+    const urls = [];
+
+    // Add the homepage
+    urls.push(SITE_URL + '/');
+
+    // Gather markdown docs
+    if (fs.existsSync(DOCS_DIR)) {
+        walk(DOCS_DIR, (filePath) => {
+            if (filePath.endsWith('.md')) {
+                const slug = getSlugFromMarkdown(filePath);
+                urls.push(SITE_URL + '/' + slug + '.html');
+            }
+        });
+    }
+
+    // Gather .tsx pages (non-component files in pages directory)
+    if (fs.existsSync(PAGES_DIR)) {
+        walk(PAGES_DIR, (filePath) => {
+            if (filePath.endsWith('.tsx')) {
+                const relativePath = path.relative(PAGES_DIR, filePath);
+                const slug = relativePath
+                    .replace(/\.tsx$/, '')
+                    .replace(/\/index$/, '');
+                if (slug === 'index') {
+                    // Already added as homepage
+                    return;
+                }
+                urls.push(SITE_URL + '/' + slug + '.html');
+            }
+        });
+    }
+
+    return urls;
+}
+
+/**
+ * Sleep for the given number of milliseconds.
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Submits URLs to the IndexNow API with retry logic.
+ * Retries up to MAX_RETRIES times with exponential backoff.
+ */
+async function submitToIndexNow(urls) {
+    const body = JSON.stringify({
+        host: SITE_HOST,
+        key: INDEXNOW_KEY,
+        keyLocation: KEY_LOCATION,
+        urlList: urls
+    });
+
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            console.log('IndexNow submission attempt ' + attempt + '/' + MAX_RETRIES + '...');
+            const response = await fetch(INDEXNOW_ENDPOINT, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json; charset=utf-8'
+                },
+                body
+            });
+
+            if (response.ok || response.status === 200 || response.status === 202) {
+                console.log('IndexNow submission successful (HTTP ' + response.status + ')');
+                return;
+            }
+
+            console.error('IndexNow returned HTTP ' + response.status + ': ' + response.statusText);
+            const responseText = await response.text().catch(() => '');
+            if (responseText) {
+                console.error('Response body: ' + responseText);
+            }
+        } catch (err) {
+            console.error('IndexNow request failed: ' + err.message);
+        }
+
+        if (attempt < MAX_RETRIES) {
+            const waitSeconds = Math.pow(2, attempt);
+            console.log('Retrying in ' + waitSeconds + ' seconds...');
+            await sleep(waitSeconds * 1000);
+        }
+    }
+
+    throw new Error('IndexNow submission failed after ' + MAX_RETRIES + ' attempts');
+}
+
+async function main() {
+    console.log('Gathering documentation page URLs...');
+    const urls = gatherPageUrls();
+    console.log('Found ' + urls.length + ' pages to submit:\n');
+    for (const url of urls) {
+        console.log('  ' + url);
+    }
+    console.log('');
+
+    await submitToIndexNow(urls);
+    console.log('Done. Bing IndexNow has been notified about ' + urls.length + ' pages.');
+}
+
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/scripts/start-foundationdb-docker.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+set -e
+
+FDB_VERSION="7.3.59"
+CONTAINER_NAME="rxdb-foundationdb"
+FDB_CLUSTER_FILE="/etc/foundationdb/fdb.cluster"
+TIMEOUT_SECONDS=30
+
+echo "# Starting FoundationDB Docker container..."
+
+# Remove any existing container
+docker rm -f "$CONTAINER_NAME" 2>/dev/null || true
+
+# Start the FoundationDB server container with host networking
+docker run -d \
+    --name "$CONTAINER_NAME" \
+    --network host \
+    -e FDB_NETWORKING_MODE=host \
+    "foundationdb/foundationdb:${FDB_VERSION}"
+
+echo "# Waiting for container to initialize..."
+sleep 2
+
+# Create the cluster file directory on the host
+sudo mkdir -p /etc/foundationdb
+
+# Copy the cluster file from the container to the host.
+# The container generates a cluster file on startup at /var/fdb/fdb.cluster.
+# With --network host and FDB_NETWORKING_MODE=host, the cluster file
+# contains an IP address reachable from the host.
+docker cp "$CONTAINER_NAME:/var/fdb/fdb.cluster" /tmp/fdb.cluster
+sudo cp /tmp/fdb.cluster "$FDB_CLUSTER_FILE"
+rm /tmp/fdb.cluster
+echo "# Cluster file contents:"
+cat "$FDB_CLUSTER_FILE"
+
+# Wait for the FoundationDB server to be reachable
+echo "# Waiting for FoundationDB to be reachable..."
+SECONDS_WAITED=0
+while [ "$SECONDS_WAITED" -lt "$TIMEOUT_SECONDS" ]; do
+    if fdbcli --exec "status minimal" --timeout 5 2>/dev/null; then
+        echo "# FoundationDB server is reachable."
+        break
+    fi
+    sleep 1
+    SECONDS_WAITED=$((SECONDS_WAITED + 1))
+done
+
+if [ "$SECONDS_WAITED" -ge "$TIMEOUT_SECONDS" ]; then
+    echo "# WARNING: Timed out waiting for FoundationDB to be reachable."
+fi
+
+# Configure the database for single-machine operation with in-memory storage engine
+echo "# Configuring database..."
+fdbcli --exec "configure new single memory" --timeout "$TIMEOUT_SECONDS" || true
+
+# Wait for the database to become available after configuration
+echo "# Waiting for database to become available..."
+SECONDS_WAITED=0
+while [ "$SECONDS_WAITED" -lt "$TIMEOUT_SECONDS" ]; do
+    STATUS=$(fdbcli --exec "status minimal" --timeout 5 2>/dev/null || echo "")
+    if echo "$STATUS" | grep -q "The database is available"; then
+        echo "# FoundationDB is ready!"
+        exit 0
+    fi
+    sleep 1
+    SECONDS_WAITED=$((SECONDS_WAITED + 1))
+done
+
+echo "# ERROR: FoundationDB did not become available within ${TIMEOUT_SECONDS} seconds."
+echo "# Container logs:"
+docker logs "$CONTAINER_NAME" 2>&1 | tail -50
+exit 1

package/src/change-event-buffer.ts

@@ -13,6 +13,9 @@ import type {
 import {
     requestIdlePromiseNoQueue
 } from './plugins/utils/index.ts';
+import {
+    newRxError
+} from './rx-error.ts';
 
 
 /**
@@ -140,7 +143,7 @@ export class ChangeEventBuffer<RxDocType> {
         this.processTasks();
         const ret = this.getFrom(pointer);
         if (ret === null) {
-            throw new Error('out of bounds');
+            throw newRxError('COB1');
         } else {
             ret.forEach(cE => fn(cE));
         }

package/src/custom-index.ts

@@ -26,6 +26,9 @@ import {
     INDEX_MAX,
     INDEX_MIN
 } from './query-planner.ts';
+import {
+    newRxError
+} from './rx-error.ts';
 
 
 /**
@@ -56,7 +59,7 @@ export function getIndexMeta<RxDocType>(
             fieldName
         );
         if (!schemaPart) {
-            throw new Error('not in schema: ' + fieldName);
+            throw newRxError('CI1', { fieldName });
         }
         const type = schemaPart.type;
         let parsedLengths: ParsedLengths | undefined;
@@ -84,13 +87,54 @@ export function getIndexMeta<RxDocType>(
                 return fieldValue ? '1' : '0';
             };
         } else { // number
-            getIndexStringPart = docData => {
-                const fieldValue = getValue(docData);
-                return getNumberIndexString(
-                    parsedLengths as any,
-                    fieldValue
-                );
-            };
+            /**
+             * @performance
+             * Inline the number index string generation to avoid
+             * function call overhead and redundant boundary checks.
+             * Document data in the hot path is assumed to be valid.
+             */
+            const pLengths = parsedLengths as ParsedLengths;
+            const pMin = pLengths.minimum;
+            const pMax = pLengths.maximum;
+            const pRoundedMin = pLengths.roundedMinimum;
+            const pNonDecimals = pLengths.nonDecimals;
+            const pDecimals = pLengths.decimals;
+            const pMultiplier = pLengths.multiplier;
+            if (pDecimals === 0) {
+                getIndexStringPart = docData => {
+                    let fieldValue = getValue(docData);
+                    if (typeof fieldValue === 'undefined') {
+                        fieldValue = 0;
+                    }
+                    if (fieldValue < pMin) {
+                        fieldValue = pMin;
+                    }
+                    if (fieldValue > pMax) {
+                        fieldValue = pMax;
+                    }
+                    return (Math.floor(fieldValue) - pRoundedMin).toString().padStart(pNonDecimals, '0');
+                };
+            } else {
+                getIndexStringPart = docData => {
+                    let fieldValue = getValue(docData);
+                    if (typeof fieldValue === 'undefined') {
+                        fieldValue = 0;
+                    }
+                    if (fieldValue < pMin) {
+                        fieldValue = pMin;
+                    }
+                    if (fieldValue > pMax) {
+                        fieldValue = pMax;
+                    }
+                    const flooredValue = Math.floor(fieldValue);
+                    const shifted = Math.min(
+                        Math.round((fieldValue - flooredValue) * pMultiplier),
+                        pMultiplier - 1
+                    );
+                    const str = (flooredValue - pRoundedMin).toString().padStart(pNonDecimals, '0');
+                    return str + shifted.toString().padStart(pDecimals, '0');
+                };
+            }
         }
 
         const ret: IndexMetaField<RxDocType> = {
@@ -125,10 +169,25 @@ export function getIndexableStringMonad<RxDocType>(
     const fieldNamePropertiesAmount = fieldNameProperties.length;
     const indexPartsFunctions = fieldNameProperties.map(r => r.getIndexStringPart);
 
-
     /**
      * @hotPath Performance of this function is very critical!
+     * Specialize for common field counts to avoid loop overhead.
      */
+    if (fieldNamePropertiesAmount === 1) {
+        return indexPartsFunctions[0];
+    }
+    if (fieldNamePropertiesAmount === 2) {
+        const fn0 = indexPartsFunctions[0];
+        const fn1 = indexPartsFunctions[1];
+        return (docData: RxDocumentData<RxDocType>): string => fn0(docData) + fn1(docData);
+    }
+    if (fieldNamePropertiesAmount === 3) {
+        const fn0 = indexPartsFunctions[0];
+        const fn1 = indexPartsFunctions[1];
+        const fn2 = indexPartsFunctions[2];
+        return (docData: RxDocumentData<RxDocType>): string => fn0(docData) + fn1(docData) + fn2(docData);
+    }
+
     const ret = function (docData: RxDocumentData<RxDocType>): string {
         let str = '';
         for (let i = 0; i < fieldNamePropertiesAmount; ++i) {
@@ -146,6 +205,11 @@ declare type ParsedLengths = {
     nonDecimals: number;
     decimals: number;
     roundedMinimum: number;
+    /**
+     * Pre-computed Math.pow(10, decimals) to avoid
+     * recomputing on every getNumberIndexString call.
+     */
+    multiplier: number;
 };
 export function getStringLengthOfIndexNumber(
     schemaPart: JsonSchema
@@ -167,7 +231,8 @@ export function getStringLengthOfIndexNumber(
         maximum,
         nonDecimals,
         decimals,
-        roundedMinimum: minimum
+        roundedMinimum: minimum,
+        multiplier: Math.pow(10, decimals)
     };
 }
 
@@ -233,9 +298,19 @@ export function getNumberIndexString(
     let str = nonDecimalsValueAsString.padStart(parsedLengths.nonDecimals, '0');
 
     if (parsedLengths.decimals > 0) {
-        const splitByDecimalPoint = fieldValue.toString().split('.');
-        const decimalValueAsString = splitByDecimalPoint.length > 1 ? splitByDecimalPoint[1] : '0';
-        str += decimalValueAsString.padEnd(parsedLengths.decimals, '0');
+        /**
+         * @performance
+         * Use math to extract decimal digits instead of toString().split('.')
+         * which creates intermediate strings and arrays.
+         * multiplier is pre-computed in ParsedLengths to avoid Math.pow() per call.
+         */
+        const multiplier = parsedLengths.multiplier;
+        const shifted = Math.min(
+            Math.round((fieldValue - Math.floor(fieldValue)) * multiplier),
+            multiplier - 1
+        );
+        const decimalPart = shifted.toString();
+        str += decimalPart.padStart(parsedLengths.decimals, '0');
     }
     return str;
 }
@@ -298,7 +373,7 @@ export function getStartIndexStringFromLowerBound(
                 }
                 break;
             default:
-                throw new Error('unknown index type ' + type);
+                throw newRxError('CI2', { type: type as string });
         }
     });
     return str;
@@ -331,8 +406,10 @@ export function getStartIndexStringFromUpperBound(
                 }
                 break;
             case 'boolean':
-                if (bound === null) {
+                if (bound === null || bound === INDEX_MAX) {
                     str += '1';
+                } else if (bound === INDEX_MIN) {
+                    str += '0';
                 } else {
                     const boolToStr = bound ? '1' : '0';
                     str += boolToStr;
@@ -357,7 +434,7 @@ export function getStartIndexStringFromUpperBound(
                 }
                 break;
             default:
-                throw new Error('unknown index type ' + type);
+                throw newRxError('CI2', { type: type as string });
         }
     });
     return str;